Skip to content

MCP ZigBee2MQTT

This guide enables ZigBee2MQTT integration through the local Dockerized MCP2ZigBee2MQTT server registered in .mcp.json.

Scope

Current implementation in this repository provides:

  • Docker-only MCP transport
  • Pinned immutable runtime image digest
  • Pinned upstream source commit checkout
  • Local SQLite state at .data/mcp-zigbee2mqtt/data/zigbee2mqtt.db
  • Bitwarden-driven hydration of MQTT credentials

Runtime image: docker.io/node:22-bookworm-slim

Source pin: ichbinder/MCP2ZigBee2MQTT@dc3e5dea11238c5e55e8f79e6117f05a2507d927

1. Prepare credentials in Bitwarden

Expected Bitwarden item:

  • Item name: MQTT MCP
  • Field MQTT_BROKER_URL: broker URL (for example, mqtt://host.docker.internal:1883)
  • Optional field MQTT_USERNAME: broker username
  • Optional field MQTT_PASSWORD: broker password
  • Optional field MQTT_BASE_TOPIC: defaults to zigbee2mqtt
  • Optional field API_KEY: only used for HTTP mode upstream
  • Optional field LOG_LEVEL: defaults to error

Hydrate local .env from vault fields:

just bw-mqtt-credentials-pull

Compatibility alias (still supported):

just bw-zigbee2mqtt-credentials-pull

Or hydrate all supported MCP secrets in one pass:

just bw-env-hydrate

2. Validate MCP wiring

Run from the hermetic Nix shell:

just sync-ai
just mcp-health

Expected summary includes:

  • zigbee2mqtt MCP docker image: docker.io/node@sha256:<digest>

3. Authentication and Home Assistant

The MCP server authenticates to your MQTT broker, not directly to Home Assistant.

If ZigBee2MQTT uses the Home Assistant Mosquitto add-on, create a dedicated Home Assistant user for MQTT and use that username/password in the Bitwarden item fields above.

4. Example prompts

In your MCP-capable client, run prompts similar to:

Use the zigbee2mqtt MCP server to list all devices.

Use the zigbee2mqtt MCP server to find devices with temperature capability.

Use the zigbee2mqtt MCP server to turn on kitchen_lamp.

Troubleshooting

  • No devices found: verify MQTT_BASE_TOPIC matches your ZigBee2MQTT config.
  • Connection failures: verify MQTT_BROKER_URL and broker reachability from Docker.
  • Authentication failures: verify MQTT_USERNAME and MQTT_PASSWORD, then re-run just bw-mqtt-credentials-pull.
  • If your broker is on the host, prefer mqtt://host.docker.internal:1883.