ChirpStack

chirpstack-mcp-server

ChirpStack v4 向けの MCP サーバーです。 AI エージェント（Claude Code、Claude Desktop、または任意の MCP クライアント）から LoRaWAN ネットワークを管理できます。また、デバイスアプリケーションの開発で重要な、デバイスのライブデバッグも行えます。ダウンリンクをキューに登録し、届いたアップリンクやイベントを監視し、ペイロードコーデックを反復的に調整して、リンク品質を確認できます。すべてコーディングセッション内で行えます。

このサーバーは、単一の API キーを使って ChirpStack のネイティブ gRPC API と通信します。デバイスやベンダー固有のロジックは含みません。

Claude Code の実際の未編集セッション（2.5 倍速、ChirpStack MCP ツールのみを使用）：エージェントがデバイスプロファイルのコーデックを読み取り、生のアップリンクから切断されたプローブを示すセンチネル値を見つけ、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	平文の HTTP/2 ではなく TLS を使用します
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..."
      }
    }
  }
}

ツールセット

ツールはグループ化されているため、エージェントには必要なものだけが表示されます。名前は <toolset>_<verb> 形式です。

ツールセット	デフォルト	ツール
devices	はい	list、get、create、update、delete、set_keys、activate、deactivate、flush_dev_nonces、enqueue、queue_get、queue_flush、metrics
debug	はい	server_info、capture_start、capture_read、capture_stop、capture_list、wait_for_event、device_recent_events
applications	はい	list、get、create、update、delete、list_device_tags
profiles	はい	list、get、create、update、delete、profile_set_codec、list_vendors、list_adr_algorithms
gateways	はい	list、get、create、update、delete、metrics
multicast	いいえ	グループ CRUD、デバイスの追加／削除、enqueue、queue_list、queue_flush
fuota	いいえ	デプロイメント CRUD、start、デバイスの追加／削除／一覧表示、list_jobs
integrations	いいえ	integration_list/get/set/delete — ChirpStack の 10 種類すべての統合に対応する汎用の set を 1 つ提供します。integration_get は include_secrets=true を指定しない限り、保存済みの認証情報をマスキングします
tenants	いいえ	テナント CRUD、テナントユーザー、API キー
relay	いいえ	リレーデバイスとリレーゲートウェイ

CHIRPSTACK_TOOLSETS=devices,debug,profiles,multicast または CHIRPSTACK_TOOLSETS=all を指定して、ツールセットを追加で有効にできます。 接続と API キーを確認するため、エージェントは最初に server_info を呼び出してください。ChirpStack はログイン済みユーザーセッションにのみこれらの情報を提供し、API キーには提供しないため、chirpstack_version／regions フィールドは null または空で返されることがあります。

ライブデバッグ

ChirpStack はデバイスごとに直近約 10 件のイベントを保持し、新しいイベントをストリーミングします。debug ツールセットを使うと、ツール呼び出しの合間にエージェントが利用できるようになります。

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) はセッションを保持せずにその履歴を返します。

Class A デバイスがダウンリンクを受信するのは、次のアップリンクの後です。Class 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 はこの値を拒否します。
• ChirpStack の API ポートはデフォルトで平文のため、デフォルトでは平文 HTTP/2（h2c）を使用します。平文 h2c では API キーがワイヤ上で平文のベアラートークンとして送信されます。信頼できる LAN 上でのみ使用し、それ以外の場所では CHIRPSTACK_TLS=true（gRPC を話す TLS 終端プロキシの背後で）または VPN を使用してください。
• streamable-http 自体には認証機能がなく、127.0.0.1 にバインドされます。パブリックインターフェイスに公開しないでください。
• HTTP トランスポートは Host／Origin ヘッダーを検証するため（DNS リバインディング対策）、オペレーターのブラウザーで開いたウェブページからループバックリスナーへの MCP セッションを開くことはできません。
• 破壊的なツールには注釈（destructiveHint）が付けられているため、MCP クライアントは実行前に確認を求めることができます。
• tenants ツールセットを有効にすると、エージェントは 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