zigbee2mqtt-mcp — an external MCP server over the bridge API (alternative to the mcp-server extension)

[alexpfau]

I've published an MCP server that lets an AI assistant administer a Zigbee2MQTT install through the documented MQTT bridge API.

Worth saying up front that there are already two other Zigbee2MQTT MCP servers, taking different routes:

• mcp-server by @pranjal-joshi runs inside z2m as an external extension (Streamable HTTP, requires enable_external_js).
• loryanstrant/Zigbee2MQTT-MCP uses the frontend WebSocket API, with both stdio and HTTP transports.

Mine is the third route: an external stdio client on the MQTT bridge API. The reason I went that way is that the bridge API is the documented, versioned message contract the other integrations build on, so it is the surface least likely to shift under a long-lived tool. It also needs no changes to your z2m install, opens no listening port, and every tool carries MCP annotations so a client can distinguish read-only from destructive without parsing prose.

The trade-off is real in both directions: the WebSocket route reaches installs where the broker isn't exposed and gives you one HTTPS endpoint through a proxy, which mine can't. Pick whichever matches what you can reach and how long you need it to keep working.

Design: stateless. It subscribes to the retained bridge/* topics for a complete picture in a few hundred milliseconds, and issues bridge/request/* calls correlated to bridge/response/* via the transaction property. No database, no daemon.

Two things I'd appreciate a sanity check on from people who know the internals better than I do:

1. I harvest linkquality, battery and update from device state topics, which aren't retained — so on a cold start they're absent until devices report. I expose an opt-in listen window and fall back to networkmap for authoritative link quality. Is there a better source I've missed?
2. I treat bridge/health's per-device leave_count and network_address_changes as signals that a device is unstable on the mesh. Is that a fair reading of those counters?

A third question, now that there are three implementations: is the frontend WebSocket API considered a supported integration surface, or is the MQTT bridge API the intended one for third-party tools? disable_ui_serving suggests the WebSocket is meant to be consumable on its own, but I can't find the message protocol documented anywhere.

Early release, tested against one EmberZNet estate of 50 devices on 2.12.1.

https://github.com/alexpfau/zigbee2mqtt-mcp · npx zigbee2mqtt-mcp · MIT