alexpfau/zigbee2mqtt-mcp

A Model Context Protocol server for **administering** a Zigbee2MQTT estate.
Most Zigbee integrations already let an assistant turn a light on. This one is for the layer underneath: mesh health, weak links, devices that keep rejoining, stale batteries, firmware updates, pairing, binding, reporting intervals and device options — the things you normally open the Zigbee2MQTT frontend for.
It talks directly to the Zigbee2MQTT MQTT bridge API, so it works regardless of whether you use Home Assistant, Node-RED, openHAB or nothing at all. Tested against Zigbee2MQTT 2.x; several tools depend on bridge endpoints that only exist there, including bridge/health, device/binds/clear and the OTA scheduling topics.
Why this exists
If you already run Home Assistant, your Zigbee devices are exposed there and an assistant can control them. What Home Assistant does *not* expose is the bridge itself: link quality, mesh topology, interview state, OTA availability, permit_join, device options, bindings and reporting configuration. This server fills exactly that gap.
Design
- **No database.** Zigbee2MQTT publishes its bridge topics as retained messages, so a fresh subscription yields a complete picture in a few hundred milliseconds. The server keeps only the latest payload per topic in memory.
- **No daemon.** Pure stdio. It starts and dies with the MCP session.
- **Correlated requests.** Every bridge/request/* carries a transaction id and is matched to its bridge/response/*, so concurrent calls cannot cross wires.
- **Tiered writes.** Destructive operations are gated behind a write mode *and* an explicit confirm argument.
Install
Requires Node.js 22 or newer and network access to the MQTT broker that Zigbee2MQTT uses.
VS Code / GitHub Copilot
Add to your MCP configuration:
Claude Desktop
> Point Z2M_MQTT_URL at your **MQTT broker**, not at the Zigbee2MQTT frontend port. If Zigbee2MQTT's configuration.yaml says mqtt.server: mqtt://192.168.1.10:1883, use that value verbatim.
> Behind a corporate npm proxy? If npm config get registry is not https://registry.npmjs.org/, your proxy's upstream feed may not carry this package. Add an explicit override to the args rather than changing your global registry:
> "args": ["-y", "--registry", "https://registry.npmjs.org/", "zigbee2mqtt-mcp"]
Configuration
| Variable | Default | Purpose |
| --- | --- | --- |
| Z2M_MQTT_URL | *required* | Broker URL. mqtt://, mqtts://, ws://, wss:// |
| Z2M_MQTT_USERNAME / Z2M_MQTT_PASSWORD | – | Broker credentials |
| Z2M_BASE_TOPIC | zigbee2mqtt | Must match mqtt.base_topic |
| Z2M_MQTT_CLIENT_ID | zigbee2mqtt-mcp- | Override if your broker requires a fixed client ID |
| Z2M_WRITE_MODE | safe | off, safe or full |
| Z2M_LOG_LEVEL | error | Diagnostics on stderr |
| Z2M_WEAK_LINK_THRESHOLD | 30 | Link quality below this is flagged |
| Z2M_LOW_BATTERY_THRESHOLD | 20 | Battery percentage below this is flagged |
| Z2M_STALE_HOURS | 24 | Hours of silence before a device is stale |
| Z2M_CONNECT_TIMEOUT_MS | 10000 | Broker connect timeout |
| Z2M_REQUEST_TIMEOUT_MS | 15000 | Default bridge request timeout |
| Z2M_MQTT_REJECT_UNAUTHORIZED | true | Set false for self-signed TLS |
| Z2M_MQTT_CA / _CERT / _KEY | – | Paths to TLS material |
Write modes
Tools above the active tier are not registered at all, so a model cannot reach for them.
| Mode | Exposes |
| --- | --- |
| off | Read-only tools |
| safe | **Default.** Read plus non-destructive writes: pairing, options, rename, configure, interview, binding, reporting, groups, state |
| full | Everything, including device removal, OTA flashing, Touchlink and bridge restart |
Irreversible tools (z2m_remove_device, z2m_ota_update, z2m_touchlink, z2m_restart_bridge, z2m_set_bridge_options) additionally require confirm: true on every call. Three safe tools reduce state rather than only adding to it, so they are annotated destructive: z2m_rename_device, z2m_manage_group and z2m_bind. Their reducing actions also require confirm: true — z2m_manage_group (remove, remove_all_members) and z2m_bind (clear). z2m_rename_device is annotated destructive because it breaks anything referencing the old name, but stays unconfirmed since renaming back restores it.