chirpstack-mcp-server

An MCP server for ChirpStack v4. It lets an AI agent (Claude Code, Claude Desktop, or any MCP client) manage a LoRaWAN network and — the part that matters while you are building a device application — debug devices live: queue a downlink, watch the uplinks and events as they arrive, iterate a payload codec, and inspect link quality, all from the coding session.

The server talks to ChirpStack's native gRPC API with a single API key. It carries no device- or vendor-specific logic.

Real recording: device_recent_events shows the backlog, wait_for_event returns the next uplink the moment ChirpStack receives it, decoded by the device profile's codec.

Install

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

Configure

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 / generic MCP config

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

Toolsets

Tools are grouped so an agent only sees what it needs. Names are <toolset>_<verb>.

Enable more with CHIRPSTACK_TOOLSETS=devices,debug,profiles,multicast or CHIRPSTACK_TOOLSETS=all. server_info is the first call an agent should make to check the connection and the API key; its chirpstack_version/regions fields may come back null/empty since ChirpStack only serves those to a logged-in user session, never to an API key.

Live debugging

ChirpStack keeps the last ~10 events per device and streams new ones. The debug toolset turns that into something an agent can use between tool calls:

1. capture_start(target, kind) opens a background stream (events or frames for a device, gateway_frames for a gateway) into a 500-item ring buffer and returns a session_id.
2. device_enqueue(dev_eui, f_port, data_hex=...) queues the downlink.
3. capture_read(session_id, since_seq) returns everything that arrived since the last read — decoded uplinks (f_port, f_cnt, data_hex, codec object, per-gateway rssi/snr), ack/txack for the downlink, log entries when something went wrong.
4. capture_stop(session_id) when done. Idle sessions expire after 30 minutes.

For quick looks: wait_for_event(dev_eui, timeout_s) blocks up to 60 s for the next live event — it only returns events newer than the moment it was called, never the history ChirpStack replays; device_recent_events(dev_eui) returns that history without keeping a session.

Class A devices only receive a downlink after their next uplink; Class C devices get it right away.

Security notes

• The API key is read from the environment and never appears in tool output. device_get hides root keys unless asked with include_keys=true.
• device_get/multicast_get hide session keys unless include_keys=true.
• integration_get redacts stored credentials unless include_secrets=true.
• <redacted> is reserved: integration_set/multicast_update keep the stored value wherever it appears (so an edited _get result can be handed straight back), and integration_set/multicast_create refuse it when there is nothing to keep.
• Plain HTTP/2 (h2c) is the default because ChirpStack's API port is plain by default. Plain h2c sends the API key as a cleartext bearer token on the wire; use it only on a trusted LAN, and set CHIRPSTACK_TLS=true (behind a TLS-terminating proxy that speaks gRPC) or a VPN elsewhere.
• streamable-http has no authentication of its own and binds to 127.0.0.1. Do not expose it on a public interface.
• The HTTP transport validates Host/Origin headers (DNS-rebinding protection), so a web page in the operator's browser cannot open an MCP session against the loopback listener.
• Destructive tools are annotated (destructiveHint) so MCP clients can ask before running them.
• Enabling the tenants toolset lets the agent mint API keys; api_key_create returns the new token once, in its result.

Development

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

Design notes live in docs/design.md.

License

MIT © Oldřich Švéda