Zigbee2mqtt-mcp — let an AI assistant administer your Zigbee mesh (early release, testers wanted)

Share your Projects!
, , ,
1

I kept opening the Zigbee2MQTT frontend to answer the same questions: what’s offline, which batteries are dying, which devices keep falling off the mesh, what has firmware updates pending. So I built an MCP server that exposes that layer to an AI assistant.

Why not just use a Home Assistant MCP server? If your Zigbee devices are in HA, an assistant can already control them. What HA doesn’t expose is the bridge itself: link quality, mesh topology, interview state, OTA availability, permit_join, bindings, reporting intervals and device options. That gap is the point of this.

There are at least two other Zigbee2MQTT MCP servers worth knowing about. mcp-server runs inside Zigbee2MQTT as an external extension (marked unstable), and loryanstrant/Zigbee2MQTT-MCP talks to the Zigbee2MQTT frontend WebSocket API and supports both stdio and HTTP. Mine takes a third route — external, stdio, talking only to the MQTT bridge API. Relevant if you run the HA add-on: you don’t have to modify the add-on, enable external JavaScript, or open a port. All three are worth a look.

The tool I actually use is z2m_health_report — one call returning offline devices, weak links, stale devices, low batteries, failed interviews, pending OTA, and devices repeatedly rejoining or changing network address. First run on my own network found 4 offline devices, 6 batteries under 20% and 5 pending firmware updates I didn’t know about.

Being upfront about maturity: v0.3.x and a few days old. Developed against exactly one estate — 50 devices, EmberZNet coordinator, Zigbee2MQTT 2.12. Other adapters (TI CC2652/CC1352, deCONZ/ConBee), TLS and WebSocket brokers, and large estates are unverified. About 16 of its 23 tools have been exercised against real hardware; the destructive ones I deliberately haven’t fired at my own live network.

Destructive tools (device removal, OTA flashing, Touchlink, bridge restart) are off by default behind a write-mode setting and additionally require an explicit confirmation argument. Every tool also declares MCP annotations, so a client can tell read-only from destructive without guessing.

npx zigbee2mqtt-mcp — MIT, TypeScript, two runtime dependencies. Also runs as a container.
GitHub: GitHub - alexpfau/zigbee2mqtt-mcp: MCP server for administering a Zigbee2MQTT estate: health reporting, mesh diagnostics, OTA updates, pairing, binding and device options over the MQTT bridge API. · GitHub

I’d particularly value testers on non-EmberZNet adapters, and anyone whose advanced.last_seen or availability settings differ from mine — the server detects those and degrades with a hint rather than silently returning nothing, but that logic has only met one configuration. Issues and PRs very welcome; please include your adapter type and Zigbee2MQTT version from z2m_bridge_info.

2

Nice work!
I also built one recently: GitHub - loryanstrant/Zigbee2MQTT-MCP: A Model Context Protocol server for Zigbee2MQTT · GitHub

Isn’t AI just the greatest? :slight_smile:

3

Ha — that’s a good sign for the idea, if slightly deflating for both our repos!

I genuinely didn’t find yours before I started, and I should have looked harder. I evaluated one abandoned implementation, concluded there was a gap, and went ahead. GitHub search for “zigbee2mqtt mcp” returns nothing useful even now, which is part of it — I only came across yours via Glama’s related-servers listing, days later.

Reading through it, the interesting thing is that we picked different integration surfaces. You talk to the frontend WebSocket API; I talk to the MQTT bridge API. That’s a real trade-off rather than a duplication: yours works when the broker isn’t reachable but the frontend is, and gives you one HTTPS endpoint through a reverse proxy — much better for remote or hosted setups. Mine works when the frontend is disabled and rides a documented, versioned message contract, but needs broker credentials.

Things you have that I don’t: HTTP transport, a real test suite, container hardening. Things I have that you don’t: binding, reporting-interval configuration, bridge logs. Neither of those lists is a moat — they’re just where we each started.

I’ve added a link to yours in my post above and in the Zigbee2MQTT discussion, since anyone choosing between them should see both. And yes — I’d have been quite happy to find yours first and contribute instead.

4

is it possible to use mcp for bindings? or binding advice?

5

Yes to both.

Binding: z2m_bind handles bind, unbind and clear, to a device or a group, with an optional cluster list. It’s in the default safe write mode. It also takes from_endpoint and to_endpoint, which is what you need for a multi-button remote — binding just the left rocker, say.

Use v0.7.0 or later and it works as described.

Binding advice: partly, and it works better than I expected when I went to check. z2m_get_device returns each endpoint’s input and output clusters plus the bindings already in place, so an assistant can work out what’s valid rather than guess.

On my own mesh a Hue wall switch reports output clusters genIdentify, genGroups, genOnOff, genLevelCtrl, genOta, and an IKEA bulb reports input clusters including genOnOff, genLevelCtrl, genGroups. The sensible bind set is the overlap — genOnOff and genLevelCtrl — or bind to a group if you want several lights on one button.

What’s missing is a tool that does that reasoning for you. Right now the model has to fetch both devices and work out the intersection itself. A z2m_suggest_bindings that takes a source device and returns viable targets with the clusters they share, and flags things like “this remote already binds genOnOff to X”, would be a much better answer. Happy to build it if that’s the shape you had in mind.

What are you trying to bind?

6

that’s exactly my problem don’t know what is possible to bind. so I will als check all my kind of switches and light bulb. what is possible to bind :slight_smile:

I gonna test the MCP now, and report back

7

Please let me know what works and what doesn’t. Feel free to open an issue in my GitHub repo and ask for changes.

8

Very nich works great. But i have not that xompatible switches. The ikeas are done now :wink: