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 with any Zigbee2MQTT 1.17+ installation regardless of whether you use Home Assistant, Node-RED, openHAB or nothing at all.

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.

Related MCP server: music-assistant-mcp-plus

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 20 or newer and network access to the MQTT broker that Zigbee2MQTT uses.

npx zigbee2mqtt-mcp

VS Code / GitHub Copilot

Add to your MCP configuration:

{
  "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"
      }
    }
  }
}

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

Write modes

Tools above the active tier are not registered at all, so a model cannot reach for them.

Irreversible tools (z2m_remove_device, z2m_ota_update, z2m_touchlink, z2m_restart_bridge, z2m_set_bridge_options) additionally require confirm: true on every call.

Every tool also advertises MCP tool annotations so a client can decide what may run without prompting:

Opt in to the destructive tier only when you want it:

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

Tools

Read

Safe writes

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

Full writes

z2m_remove_device, z2m_ota_update, z2m_restart_bridge, z2m_set_bridge_options, z2m_coordinator_check, z2m_touchlink

Data availability caveats

Some fields depend on your Zigbee2MQTT configuration. The server detects what is available and tells you rather than silently returning nothing.

Example prompts

• "Is my Zigbee network healthy?"

• "Which devices have the weakest signal?"

• "Which batteries need replacing?"

• "Any firmware updates available?"

• "Open the network for pairing via the kitchen router for two minutes."

• "This sensor stopped reporting temperature — fix it."

• "Bind the hallway remote to the hallway light so it works if the bridge is down."

Development

npm install
npm run build
npm run watch

# 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

Note that an MCP server may receive requests concurrently. When testing ordering, await each response before sending the next, as roundtrip.mjs does — piping several requests at once will produce misleading results.

Releases are tag-driven: npm version <patch|minor|major> then git push --follow-tags. CI publishes to npm with provenance, rewrites server.json's version from the tag and publishes to the MCP Registry, then creates the GitHub release. The version committed in server.json is therefore not authoritative — the tag is.

Safety

This server can remove devices from your network and flash firmware. Both are irreversible and OTA failures can brick hardware. Those tools live in the full tier, which is not enabled by default — you must opt in with Z2M_WRITE_MODE=full. Broker credentials are read from the environment and never logged.

Status

Early release. Developed and tested against a 50-device EmberZNet estate on Zigbee2MQTT 2.12.x. Other adapters (Texas Instruments, deCONZ/ConBee, zStack), TLS and WebSocket brokers, and large estates are unverified. Bug reports and pull requests are very welcome — please include your adapter type and Zigbee2MQTT version from z2m_bridge_info.

License

MIT