zigbee2mqtt-mcp

zigbee2mqtt-mcp

Zigbee2MQTT環境を管理するためのModel Context Protocolサーバーです。

ほとんどのZigbee連携機能では、アシスタントから照明を点灯できます。このサーバーが対象とするのは、その基盤となる領域です。メッシュの健全性、リンクの弱い箇所、再接続を繰り返すデバイス、古くなったバッテリー、ファームウェアの更新、ペアリング、バインド、レポート間隔、デバイスオプションなど、通常ならZigbee2MQTTのフロントエンドを開いて操作する項目です。

Zigbee2MQTTのMQTTブリッジAPIと直接通信するため、Home Assistant、Node-RED、openHABを使用しているかどうかにかかわらず動作します。Zigbee2MQTT 2.xでテスト済みです。bridge/health、device/binds/clear、OTAスケジューリングのトピックなど、複数のツールは2.xにのみ存在するブリッジエンドポイントに依存しています。

このプロジェクトの目的

すでにHome Assistantを運用している場合、Zigbeeデバイスはそこで公開されており、アシスタントから制御できます。一方、Home Assistantで公開されていないのはブリッジそのものです。リンク品質、メッシュトポロジー、インタビューの状態、OTAの利用可否、permit_join、デバイスオプション、バインド、レポート設定などです。このサーバーは、まさにその不足を補います。

設計

• データベース不要。 Zigbee2MQTTはブリッジのトピックを保持メッセージとして公開するため、新たにサブスクライブすると、数百ミリ秒で全体像を取得できます。サーバーは各トピックの最新のペイロードのみをメモリに保持します。
• デーモン不要。 stdioのみで動作します。MCPセッションとともに起動し、終了します。
• リクエストの相関。 すべてのbridge/request/*にtransaction IDが付与され、対応するbridge/response/*と照合されるため、並行する呼び出しが混線することはありません。
• 段階的な書き込み。 破壊的な操作には、書き込みモードに加えて、confirm引数による明示的な確認が必要です。

インストール

Node.js 22以降と、Zigbee2MQTTが使用するMQTTブローカーへのネットワークアクセスが必要です。

npx zigbee2mqtt-mcp

VS Code / GitHub Copilot

MCP設定に追加します。

{
  "servers": {
    "zigbee2mqtt": {
      "command": "npx",
      "args": ["-y", "zigbee2mqtt-mcp"],
      "env": {
        "Z2M_MQTT_URL": "mqtt://192.168.1.10:1883",
        "Z2M_MQTT_USERNAME": "mqtt",
        "Z2M_MQTT_PASSWORD": "${input:z2mPassword}"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "zigbee2mqtt": {
      "command": "npx",
      "args": ["-y", "zigbee2mqtt-mcp"],
      "env": {
        "Z2M_MQTT_URL": "mqtt://192.168.1.10:1883"
      }
    }
  }
}

Z2M_MQTT_URLにはZigbee2MQTTのフロントエンドのポートではなく、MQTTブローカーを指定してください。Zigbee2MQTTのconfiguration.yamlにmqtt.server: mqtt://192.168.1.10:1883と記載されている場合は、その値をそのまま使用してください。

企業のnpmプロキシを経由していますか？npm config get registryの値がhttps://registry.npmjs.org/でない場合、プロキシのアップストリームフィードにこのパッケージが含まれていない可能性があります。グローバルのレジストリを変更するのではなく、引数に明示的なオーバーライドを追加してください。 "args": ["-y", "--registry", "https://registry.npmjs.org/", "zigbee2mqtt-mcp"]

設定

変数	デフォルト	目的
Z2M_MQTT_URL	必須	ブローカーの URL。mqtt://、mqtts://、ws://、wss://
Z2M_MQTT_USERNAME / Z2M_MQTT_PASSWORD	–	ブローカーの認証情報
Z2M_BASE_TOPIC	zigbee2mqtt	mqtt.base_topic と一致させる必要があります
Z2M_MQTT_CLIENT_ID	zigbee2mqtt-mcp-<pid>	ブローカーが固定のクライアント ID を要求する場合に上書きします
Z2M_WRITE_MODE	safe	off、safe、full
Z2M_LOG_LEVEL	error	stderr への診断出力
Z2M_WEAK_LINK_THRESHOLD	30	リンク品質がこの値を下回るとフラグが立ちます
Z2M_LOW_BATTERY_THRESHOLD	20	バッテリー残量がこのパーセンテージを下回るとフラグが立ちます
Z2M_STALE_HOURS	24	デバイスが stale とみなされるまでの無通信時間
Z2M_CONNECT_TIMEOUT_MS	10000	ブローカー接続のタイムアウト
Z2M_REQUEST_TIMEOUT_MS	15000	デフォルトのブリッジリクエストタイムアウト
Z2M_MQTT_REJECT_UNAUTHORIZED	true	自己署名 TLS の場合は false に設定します
Z2M_MQTT_CA / _CERT / _KEY	–	TLS マテリアルへのパス

書き込みモード

アクティブなティアを超えるツールはそもそも登録されないため、モデルがそれらを呼び出すことはできません。

モード	公開されるもの
off	読み取り専用ツール
safe	デフォルト。 読み取りに加えて、非破壊的な書き込み: ペアリング、オプション、名前変更、設定、インタビュー、バインディング、レポーティング、グループ、状態
full	デバイスの削除、OTA 書き込み、Touchlink、ブリッジ再起動を含むすべて

不可逆的なツール（z2m_remove_device、z2m_ota_update、z2m_touchlink、z2m_restart_bridge、z2m_set_bridge_options）は、さらにすべての呼び出しで confirm: true を必要とします。3 つの safe ツールは状態を追加するだけでなく減少させるため、破壊的であると注釈されています: z2m_rename_device、z2m_manage_group、z2m_bind です。これらの減少を伴う操作も confirm: true を必要とします — z2m_manage_group（remove、remove_all_members）と z2m_bind（clear）です。z2m_rename_device は、古い名前を参照しているものを壊すため破壊的であると注釈されていますが、名前を戻せば復元されるため確認は不要です。

また、すべてのツールは MCP のツール注釈を公開しているため、クライアントはプロンプトなしで何を実行してよいかを判断できます:

注釈	ここでの意味
readOnlyHint: true	9 つの読み取りツール。ネットワークを決して変更しません。
destructiveHint: true	z2m_remove_device、z2m_ota_update、z2m_touchlink、z2m_restart_bridge、z2m_set_bridge_options、さらに z2m_rename_device、z2m_manage_group、z2m_bind
idempotentHint	呼び出しを繰り返しても追加の効果がない場合は true
openWorldHint: true	常に — すべてのツールは実際に稼働している Zigbee ネットワークにアクセスします

注釈はティアではなくツールを表します。safe のツールでも破壊的であり得ます。どのツールが登録されるかはティアが決め、何について確認すべきかは注釈がクライアントに伝えます。

破壊的なティアは、必要なときだけオプトインしてください:

"env": { "Z2M_WRITE_MODE": "full" }

ツール

読み取り

ツール	目的
z2m_connection_status	ブローカーへの到達性、TLS の状態、キャッシュされたメッセージ数 — まだ何も設定されていない場合でも、例外を投げずに報告します
z2m_bridge_info	バージョン、コーディネーター、チャネル、PAN ID、permit_join、restart_required、ランタイム統計
z2m_list_devices	タイプ、可用性、リンク品質、バッテリー、保留中の更新でデバイスをフィルタおよびソートします
z2m_get_device	Exposes、設定可能なオプション、エンドポイント、バインディング、設定済みのレポーティング、現在の状態
z2m_health_report	一括の全構成監査を 1 回の呼び出しで実行します
z2m_network_map	親、深さ、リンク品質、孤立検出を含むメッシュトポロジー
z2m_list_groups	グループ、メンバー、シーン
z2m_get_logs	ブリッジログとライフサイクルイベント。バッファリングまたはライブ監視に対応
z2m_coordinator_check	コーディネーターのメモリから欠落しているルーター（Texas Instruments のアダプターのみ）

安全な書き込み

z2m_check_updates、z2m_permit_join、z2m_set_device_options、z2m_rename_device、z2m_configure_device、z2m_interview_device、z2m_set_state、z2m_manage_group、z2m_bind、z2m_configure_reporting

完全な書き込み

z2m_remove_device、z2m_ota_update、z2m_restart_bridge、z2m_set_bridge_options、z2m_touchlink

データの利用可否に関する注意事項

一部のフィールドは Zigbee2MQTT の設定によって異なります。サーバーは利用可能なデータを検出し、何も返さずに済ませるのではなく、その旨を通知します。

フィールド	必要な設定	設定がない場合
last_seen	advanced.last_seen を ISO_8601 などに設定（デフォルトは disable）	鮮度チェックはスキップされ、ヒントが返されます
availability	availability.enabled: true	オフライン検出はスキップされ、ヒントが返されます
linkquality、battery、update	デバイスからのライブ通信 — Zigbee2MQTT はデバイスの状態トピックを保持しません	短時間リッスンするには collect_seconds を指定するか、信頼できるリンク品質を確認するには z2m_network_map を使用します
z2m_coordinator_check	コーディネーターのバックアップに対応したアダプター（TI zStack、Silicon Labs EmberZNet。deCONZ と ZiGate は非対応）	非対応のアダプターではエラーが返されます。z2m_bridge_info で想定される内容を確認できます

セキュリティに関する注意事項

• ブローカー URL に認証情報が含まれる場合があります（mqtt://user:pass@host）。URL がモデルに返されたりログに書き込まれたりする際は、常に認証情報が伏せられます。また、MQTT クライアントからのエラーテキストも、プロセス外に出る前に秘匿化されます。Zigbee2MQTT は起動時に独自のブローカー URL をログに記録するため、z2m_get_logs が中継する行も同様に秘匿化されます。
• safe モードでは、ロック、バルブ、サイレンなどを含め、z2m_set_state を介してメッシュ上のあらゆる機器を作動させることができます。それが問題になる場合は off を使用してください。
• z2m_permit_join は、指定した時間、近くにあるあらゆる Zigbee デバイスにネットワークへの参加を許可します。一般的で元に戻せる操作であるため safe に含まれていますが、セキュリティ境界に関わる操作です。

プロンプトの例

• 「Zigbee ネットワークの状態に問題はありますか？」
• 「信号が最も弱いデバイスはどれですか？」
• 「交換が必要なバッテリーはありますか？」
• 「利用できるファームウェア更新はありますか？」
• 「キッチンのルーター経由で、2 分間ネットワークをペアリング可能な状態にしてください。」
• 「このセンサーが温度を報告しなくなりました。直してください。」
• 「ブリッジが停止しても使えるように、廊下のリモコンを廊下の照明にバインドしてください。」

開発

npm install
npm run build
npm run watch

# Unit tests. No broker required; they run on every push across Node 22 and 24.
npm test

# Manual smoke test against a real instance
Z2M_MQTT_URL=mqtt://192.168.1.10:1883 node scripts/smoke.mjs
Z2M_MQTT_URL=mqtt://192.168.1.10:1883 node scripts/smoke.mjs z2m_list_devices '{"only_problems":true}'

# Sequential read-after-write test. Renames a device and creates a group, then
# restores both, including on failure. Set Z2M_TEST_DEVICE to pick the device,
# or ROUNDTRIP_GROUPS_ONLY=1 to skip the rename.
Z2M_MQTT_URL=mqtt://192.168.1.10:1883 node scripts/roundtrip.mjs

MCP サーバーはリクエストを同時に受信することがあります。実行順序をテストする際は、roundtrip.mjs のように、次のリクエストを送信する前に各レスポンスを待ってください。複数のリクエストを一度にパイプで送信すると、誤解を招く結果になります。

単体テストでは、ヘルス分類、機能検出、トピックルーティング、書き込みモードのゲート制御、設定の解析を対象としています。設計上、ブローカーを必要としないため、実際のメッシュが必要なテストは scripts/ に配置してください。

テストスイートが成功しても、テストが実行されたことしか証明されません。そのため、scripts/mutate.mjs はソースを一度に 1 箇所ずつ変更し、テストスイートがそれぞれの変更を検出することを確認します。

node scripts/mutate.mjs          # every mutant
node scripts/mutate.mjs redact   # only mutants whose name matches

変異が生き残った場合は、その動作が実際にはテストされていないことを示し、ゼロ以外の値で終了します。修正した状態を維持する価値のある修正を加える際は、それに対応する変異も追加してください。

リリースはタグを基準に行います。npm version <patch|minor|major> を実行し、その後 git push --follow-tags を実行します。CI は provenance を付与して npm に公開し、タグから server.json のバージョンを書き換えて MCP Registry に公開した後、GitHub リリースを作成します。そのため、server.json にコミットされた version は正式なバージョンではなく、タグが正式なバージョンです。

安全性

このサーバーはネットワークからデバイスを削除したり、ファームウェアを書き込んだりできます。どちらも元に戻せず、OTA の失敗によってハードウェアが使用不能になる場合があります。これらのツールは full ティアに属しており、デフォルトでは有効になっていません。使用するには Z2M_WRITE_MODE=full を明示的に設定する必要があります。ブローカーの認証情報は環境変数から読み込まれ、ログに記録されることはありません。

ステータス

早期リリースです。Zigbee2MQTT 2.12.x 上の 50 台構成の EmberZNet 環境で開発・テストされています。その他のアダプター（Texas Instruments、deCONZ/ConBee、zStack）、TLS および WebSocket ブローカー、大規模環境は未検証です。バグ報告とプルリクエストを心よりお待ちしています — z2m_bridge_info から取得したアダプターの種類と Zigbee2MQTT のバージョンを含めてください。

ライセンス

MIT