ChirpStack

chirpstack-mcp-server

一个适用于 ChirpStack v4 的 MCP 服务。 它让 AI Agent（Claude Code、Claude Desktop 或任何 MCP 客户端）管理 LoRaWAN 网络， 并且——在开发设备应用时最重要的功能——实时调试设备： 排入一条下行消息、观察上行消息和事件到达、迭代载荷编解码器， 并检查链路质量，所有操作都可以在编码会话中完成。

该服务通过单个 API 密钥连接 ChirpStack 的原生 gRPC API。不包含任何 特定于设备或厂商的逻辑。

真实、未经剪辑的 Claude Code 会话（2.5× 速度，仅使用 ChirpStack MCP 工具）：Agent 读取设备配置文件中的编解码器，在原始上行消息中发现探头断连哨兵值，通过 profile_set_codec 部署修复，然后使用 wait_for_event 等待设备的下一条上行消息，并确认解码后的对象。

安装

uvx chirpstack-mcp-server        # run directly (needs uv: https://docs.astral.sh/uv/)
# or
pip install chirpstack-mcp-server

配置

变量	必填	默认值	含义
CHIRPSTACK_SERVER	是	—	ChirpStack API 的 host:port（Web UI 端口，通常为 8080）
CHIRPSTACK_API_KEY	是	—	在 ChirpStack → API keys 中获取的 API 密钥（租户管理员或全局管理员）
CHIRPSTACK_TOOLSETS	否	devices, debug, applications, profiles, gateways	以逗号分隔的工具集，或 all
CHIRPSTACK_TLS	否	false	使用 TLS，而非明文 HTTP/2
CHIRPSTACK_TRANSPORT	否	stdio	stdio 或 streamable-http
CHIRPSTACK_HTTP_PORT	否	8000	streamable-http 使用的端口（绑定到 127.0.0.1）

Claude Code

claude mcp add chirpstack -e CHIRPSTACK_SERVER=192.168.1.10:8080 -e CHIRPSTACK_API_KEY=eyJ... -- uvx chirpstack-mcp-server

Claude Desktop / 通用 MCP 配置

{
  "mcpServers": {
    "chirpstack": {
      "command": "uvx",
      "args": ["chirpstack-mcp-server"],
      "env": {
        "CHIRPSTACK_SERVER": "192.168.1.10:8080",
        "CHIRPSTACK_API_KEY": "eyJ..."
      }
    }
  }
}

工具集

工具按组分类，让 Agent 只看到所需工具。名称格式为 <toolset>_<verb>。

工具集	默认启用	工具
devices	是	列出、获取、创建、更新、删除、设置密钥、激活、停用、清空设备 Nonce、加入队列、获取队列、清空队列、指标
debug	是	server_info、capture_start、capture_read、capture_stop、capture_list、wait_for_event、device_recent_events
applications	是	列出、获取、创建、更新、删除、列出设备标签
profiles	是	列出、获取、创建、更新、删除、profile_set_codec、列出厂商、列出 ADR 算法
gateways	是	列出、获取、创建、更新、删除、指标
multicast	否	组 CRUD、添加/移除设备、加入队列、queue_list、queue_flush
fuota	否	部署 CRUD、启动、添加/移除/列出设备、list_jobs
integrations	否	integration_list/get/set/delete——适用于 ChirpStack 全部十种集成类型的通用设置工具；除非 include_secrets=true，否则 integration_get 会对存储的凭据进行脱敏
tenants	否	租户 CRUD、租户用户、API 密钥
relay	否	中继设备和中继网关

使用 CHIRPSTACK_TOOLSETS=devices,debug,profiles,multicast 或 CHIRPSTACK_TOOLSETS=all 启用更多工具集。 server_info 是 Agent 检查连接和 API 密钥时应首先调用的工具； 其 chirpstack_version/regions 字段可能返回 null/空值，因为 ChirpStack 只会向已登录的用户会话提供这些信息， 不会向 API 密钥提供。

实时调试

ChirpStack 会为每台设备保留最近约 10 条事件，并持续推送新事件。debug 工具集将这些事件转换为 Agent 可以在工具调用间使用的信息：

1. capture_start(target, kind) 会开启后台流（设备的 events 或 frames，网关的 gateway_frames），将数据写入包含 500 项的环形缓冲区，并返回一个 session_id。
2. device_enqueue(dev_eui, f_port, data_hex=...) 会将下行消息加入队列。
3. capture_read(session_id, since_seq) 会返回自上次读取以来收到的所有内容——已解码的上行消息（f_port、f_cnt、data_hex、编解码器 object、各网关的 rssi/snr）、该下行消息的 ack/txack，以及出错时的 log 条目。
4. 完成后调用 capture_stop(session_id)。空闲会话会在 30 分钟后过期。

快速查看时，可使用 wait_for_event(dev_eui, timeout_s)，最多阻塞 60 秒以等待下一个实时事件——它只会返回调用时刻之后的新事件，不会返回 ChirpStack 重放的历史事件；device_recent_events(dev_eui) 则会返回历史事件，且不会保留会话。

A 类设备只能在下一次上行消息后接收下行消息；C 类设备则会立即收到。

安全说明

• API 密钥从环境变量中读取，绝不会出现在工具输出中。device_get 会隐藏根密钥，除非明确设置 include_keys=true。
• device_get/multicast_get 会隐藏会话密钥，除非设置 include_keys=true。
• integration_get 会隐藏已存储的凭据，除非设置 include_secrets=true。
• <redacted> 为保留值：integration_set/multicast_update 会在其出现的任何位置保留已存储的值（因此可直接将编辑后的 _get 结果传回），而当没有可保留的值时，integration_set/multicast_create 会拒绝该值。
• 默认使用纯 HTTP/2（h2c），因为 ChirpStack 的 API 端口默认使用纯连接。纯 h2c 会在传输过程中以明文发送 API 密钥作为 bearer token；仅在可信 LAN 上使用，并在其他环境中设置 CHIRPSTACK_TLS=true（须位于支持 gRPC 的 TLS 终止代理之后）或使用 VPN。
• streamable-http 本身不提供身份验证，并绑定到 127.0.0.1。请勿将其暴露在公共网络接口上。
• HTTP 传输会验证 Host/Origin 标头（防止 DNS 重绑定），因此，操作人员浏览器中的网页无法通过环回监听器建立 MCP 会话。
• 破坏性工具会带有注释（destructiveHint），因此 MCP 客户端可以在运行前征求确认。
• 启用 tenants 工具集后，Agent 可以创建 API 密钥；api_key_create 会在结果中返回一次新令牌。

开发

uv sync
uv run pytest                     # unit tests
uv run ruff check . && uv run pyright
tests/integration/up.sh           # throwaway ChirpStack in Docker + API key
set -a; . .integration/env; set +a
uv run pytest -m integration
tests/integration/down.sh

设计说明见 docs/design.md。

许可证

MIT © Oldřich Švéda