Zigbee2MQTT

An MCP server for Zigbee2MQTT. It lets an LLM (or any MCP client) list and inspect your Zigbee devices, read and change their state, and manage the bridge — all through the Zigbee2MQTT frontend websocket API, so it needs no direct access to your MQTT broker.

Why the frontend API?

Zigbee2MQTT's frontend exposes a websocket at /api that proxies MQTT traffic as JSON {"topic": ..., "payload": ...} messages (base topic already stripped). Talking to it instead of the MQTT broker means:

• No broker dependency — works even if you don't expose MQTT on the network.
• One HTTPS endpoint — reuses your existing reverse proxy / TLS.
• Auth-ready — supports the frontend auth_token when you enable it.

Requests that change the bridge (bridge/request/*) are correlated to their bridge/response/* reply via a transaction id, with per-call timeouts. The retained device snapshot is cached on connect, so reads are instant and the connection auto-reconnects (re-priming the cache) if it drops.

Tools

Read

Control

* Protected: disabled unless Z2M_ALLOW_DESTRUCTIVE=true. Reads and set_device_state are always available.

Configuration

All configuration is via environment variables (see .env.example):

Running

Docker (recommended)

docker run -d --name zigbee2mqtt-mcp -p 8080:8080 \
  -e Z2M_FRONTEND_URL=https://zigbee2mqtt.example.com \
  ghcr.io/loryanstrant/zigbee2mqtt-mcp:latest

The MCP endpoint is then at http://<host>:8080/mcp.

Or with Compose — copy .env.example to .env, edit it, and:

docker compose up -d

Local (Python 3.11+)

pip install .
Z2M_FRONTEND_URL=https://zigbee2mqtt.example.com python -m zigbee2mqtt_mcp

stdio (local MCP client, e.g. Claude Desktop)

{
  "mcpServers": {
    "zigbee2mqtt": {
      "command": "python",
      "args": ["-m", "zigbee2mqtt_mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "Z2M_FRONTEND_URL": "https://zigbee2mqtt.example.com"
      }
    }
  }
}

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest

Security

This server exposes control of your Zigbee network. Bind it to a trusted network (LAN/VPN) or an authenticating proxy, keep Z2M_ALLOW_DESTRUCTIVE=false unless you need management tools, and never commit a populated .env. See SECURITY.md.

License

MIT — see LICENSE.