zigbee2mqtt-mcp — Claude Code MCP server: setup and features
Connects your assistant to the Zigbee2MQTT broker to audit mesh quality, manage bindings, inspect battery levels and track firmware updates.
claude mcp add --env Z2M_MQTT_URL=<Z2M_MQTT_URL> --env Z2M_MQTT_USERNAME=<Z2M_MQTT_USERNAME> --env Z2M_MQTT_PASSWORD=<Z2M_MQTT_PASSWORD> --env Z2M_BASE_TOPIC=<Z2M_BASE_TOPIC> --env Z2M_WRITE_MODE=<Z2M_WRITE_MODE> --transport stdio zigbee2mqtt-mcp -- npx -y zigbee2mqtt-mcpWhat zigbee2mqtt-mcp does
This server communicates over stdio directly with the MQTT broker that Zigbee2MQTT connects to. Zigbee2MQTT publishes state via retained messages, so the server caches incoming topics in memory without needing a separate database or background daemon. Request correlation ensures concurrent calls to the bridge never conflict.
Write actions are split into three tiers: off, safe, and full. The default safe tier handles non-destructive tasks like renaming and device bindings. Irreversible operations such as removing nodes or flashing firmware require switching to the full tier and passing an explicit confirm: true argument.
Without Node.js 22 and network access to your MQTT broker, the server cannot start. Diagnostic tools like health checks and bind clearing also require Zigbee2MQTT 2.x.
What it helps with
- diagnose weak Zigbee links and stale devices
- inspect network topology and coordinator status
- configure device bindings and reporting intervals
- toggle pairing mode without opening the Zigbee2MQTT web panel
Example prompts for the agent
- List all Zigbee devices reporting battery below 20% or weak link quality
- Check bridge coordinator status and channel configuration
- Enable permit_join on the Zigbee2MQTT bridge
How to install zigbee2mqtt-mcp
Platform CLI
claude mcp add --env Z2M_MQTT_URL=<Z2M_MQTT_URL> --env Z2M_MQTT_USERNAME=<Z2M_MQTT_USERNAME> --env Z2M_MQTT_PASSWORD=<Z2M_MQTT_PASSWORD> --env Z2M_BASE_TOPIC=<Z2M_BASE_TOPIC> --env Z2M_WRITE_MODE=<Z2M_WRITE_MODE> --transport stdio zigbee2mqtt-mcp -- npx -y zigbee2mqtt-mcpReplace <…> with your own values
Platform CLI
codex mcp add zigbee2mqtt-mcp --env Z2M_MQTT_URL=<Z2M_MQTT_URL> --env Z2M_MQTT_USERNAME=<Z2M_MQTT_USERNAME> --env Z2M_MQTT_PASSWORD=<Z2M_MQTT_PASSWORD> --env Z2M_BASE_TOPIC=<Z2M_BASE_TOPIC> --env Z2M_WRITE_MODE=<Z2M_WRITE_MODE> -- npx -y zigbee2mqtt-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"zigbee2mqtt-mcp": {
"command": "npx",
"args": [
"-y",
"zigbee2mqtt-mcp"
],
"env": {
"Z2M_MQTT_URL": "<Z2M_MQTT_URL>",
"Z2M_MQTT_USERNAME": "<Z2M_MQTT_USERNAME>",
"Z2M_MQTT_PASSWORD": "<Z2M_MQTT_PASSWORD>",
"Z2M_BASE_TOPIC": "<Z2M_BASE_TOPIC>",
"Z2M_WRITE_MODE": "<Z2M_WRITE_MODE>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"zigbee2mqtt-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"zigbee2mqtt-mcp"
],
"env": {
"Z2M_MQTT_URL": "<Z2M_MQTT_URL>",
"Z2M_MQTT_USERNAME": "<Z2M_MQTT_USERNAME>",
"Z2M_MQTT_PASSWORD": "<Z2M_MQTT_PASSWORD>",
"Z2M_BASE_TOPIC": "<Z2M_BASE_TOPIC>",
"Z2M_WRITE_MODE": "<Z2M_WRITE_MODE>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e Z2M_MQTT_URL=<Z2M_MQTT_URL> -e Z2M_MQTT_USERNAME=<Z2M_MQTT_USERNAME> -e Z2M_MQTT_PASSWORD=<Z2M_MQTT_PASSWORD> -e Z2M_BASE_TOPIC=<Z2M_BASE_TOPIC> -e Z2M_WRITE_MODE=<Z2M_WRITE_MODE> zigbee2mqtt-mcp npx -y zigbee2mqtt-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about zigbee2mqtt-mcp
How to install zigbee2mqtt-mcp in Claude Code?
Run claude mcp add zigbee2mqtt-mcp -e Z2M_MQTT_URL=<Z2M_MQTT_URL> -e Z2M_MQTT_PASSWORD=<Z2M_MQTT_PASSWORD> -- npx -y zigbee2mqtt-mcp, supplying your MQTT broker URL and credentials.
What is zigbee2mqtt-mcp used for?
It exposes bridge-level administration instead of plain light switches. You can inspect LQI link quality, manage network groups, configure bindings, and check device options through your assistant.
What prerequisites are required before setup?
You need Node.js 22 or newer, Zigbee2MQTT 2.x, and network reachability to the MQTT broker defined in your Zigbee2MQTT setup.
