# zigbee2mqtt-mcp

Connects your assistant to the Zigbee2MQTT broker to audit mesh quality, manage bindings, inspect battery levels and track firmware updates.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 34
- Author: alexpfau
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/alexpfau/zigbee2mqtt-mcp
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/zigbee2mqtt-mcp

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `Z2M_MQTT_URL`, `Z2M_MQTT_USERNAME`, `Z2M_MQTT_PASSWORD`, `Z2M_BASE_TOPIC`, `Z2M_WRITE_MODE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values

## When to use it
- 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
- 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

## Similar
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [AIHawk](https://affpapa.org/en/nevibecode/mcp/aihawk.md) — MCP server · ★ 32221
- [Skyvern](https://affpapa.org/en/nevibecode/mcp/skyvern.md) — MCP server · ★ 23263
- [SeleniumBase MCP](https://affpapa.org/en/nevibecode/mcp/seleniumbase-mcp.md) — MCP server · ★ 13169
- [Inbox Zero](https://affpapa.org/en/nevibecode/mcp/inbox-zero.md) — MCP server · ★ 12791

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md