ChirpStack

io.github.oliveresPublished by GitHub account oliveresv0.1.1Updated Oct 24, 2026

Manage and live-debug LoRaWAN devices on a ChirpStack v4 network server over its gRPC API

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

MCP server that lets an assistant manage and live-debug LoRaWAN devices on a ChirpStack v4 network server through its gRPC API.

What you can do
List, create, update, delete, activate and deactivate devices, and enqueue or flush downlinks and inspect metrics and keys. Manage applications, device profiles (including setting payload codecs), gateways and their metrics. Capture live device events and frames in background sessions, read new arrivals, wait for the next event, and review recent device events. Optionally manage multicast groups, FUOTA deployments, integrations, tenants and API keys, and relay devices and gateways.
When to use it
Useful when developing or operating a LoRaWAN deployment on ChirpStack v4 and you want the assistant to inspect devices, iterate a payload codec, queue downlinks and watch uplinks and events during a coding session.
Requirements
Runs locally as a Python package via uvx or pip, so uv or Python is needed. Requires CHIRPSTACK_SERVER (host:port of the API, usually 8080) and CHIRPSTACK_API_KEY (tenant or global admin key). Optional CHIRPSTACK_TLS, CHIRPSTACK_TOOLSETS, CHIRPSTACK_TRANSPORT and CHIRPSTACK_HTTP_PORT. Network access to the ChirpStack server.
Before you install
The API key grants tenant or global admin rights and is sent as a cleartext bearer token over plain h2c by default; use TLS or a VPN outside a trusted LAN. Tools create, update and delete devices, profiles, gateways and queues, and destructive tools are only annotated, not blocked. Enabling the tenants toolset lets the assistant mint API keys. The streamable-http transport has no authentication and must stay on loopback.

Installation

In SourceWeft

  1. Open ChirpStack in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

[Claude Code fixes a payload decoder and verifies it on the next live uplink]

Real, unedited Claude Code session (2.5× speed, only the ChirpStack MCP tools): the agent reads the device profile's codec, spots the disconnected-probe sentinel in a raw uplink, deploys a fix with profile_set_codec, then waits for the device's next uplink with wait_for_event and confirms the decoded object.

Install

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

Configure

VariableRequiredDefaultMeaning
CHIRPSTACK_SERVERyes—host:port of the ChirpStack API (the web-UI port, usually 8080)
CHIRPSTACK_API_KEYyes—API key from ChirpStack → API keys (tenant or global admin)
CHIRPSTACK_TOOLSETSnodevices, debug, applications, profiles, gatewayscomma-separated toolsets, or all
CHIRPSTACK_TLSnofalseuse TLS instead of plain HTTP/2
CHIRPSTACK_TRANSPORTnostdiostdio or streamable-http
CHIRPSTACK_HTTP_PORTno8000port for streamable-http (bound to 127.0.0.1)

Claude Code

bash
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

json
{  "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>.

ToolsetDefaultTools
devicesyeslist, get, create, update, delete, set_keys, activate, deactivate, flush_dev_nonces, enqueue, queue_get, queue_flush, metrics
debugyesserver_info, capture_start, capture_read, capture_stop, capture_list, wait_for_event, device_recent_events
applicationsyeslist, get, create, update, delete, list_device_tags
profilesyeslist, get, create, update, delete, profile_set_codec, list_vendors, list_adr_algorithms
gatewaysyeslist, get, create, update, delete, metrics
multicastnogroup CRUD, add/remove device, enqueue, queue_list, queue_flush
fuotanodeployment CRUD, start, add/remove/list devices, list_jobs
integrationsnointegration_list/get/set/delete — one generic set for all ten ChirpStack integration kinds; integration_get redacts stored credentials unless include_secrets=true
tenantsnotenant CRUD, tenant users, API keys
relaynorelay devices and relay gateways

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

bash
uv syncuv run pytest                     # unit testsuv run ruff check . && uv run pyrighttests/integration/up.sh           # throwaway ChirpStack in Docker + API keyset -a; . .integration/env; set +auv run pytest -m integrationtests/integration/down.sh

Design notes live in docs/design.md.

License

MIT © Oldřich Švéda

Source: README.md at commit b0e3d5f

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts