ZigBee2MQTT

A Model Context Protocol (MCP) server for ZigBee2MQTT that provides intelligent device discovery and control for AI assistants

typescript

GitHub Stars

typescript

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ichbinder-mcp2zigbee2mqtt": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "zigbee2mqtt-mcp",
        "node",
        "dist/index.js"
      ],
      "env": {
        "DB_PATH": "/data/zigbee2mqtt.db",
        "LOG_LEVEL": "error",
        "MQTT_PASSWORD": "your_password",
        "MQTT_USERNAME": "user",
        "MQTT_BASE_TOPIC": "zigbee2mqtt",
        "MQTT_BROKER_URL": "mqtt://localhost:1883"
      }
    }
  }
}

You run an MCP server that automatically learns the structure and capabilities of your ZigBee2MQTT devices and exposes them to AI assistants for intelligent discovery and control. It stores only metadata and schemas, keeping the footprint small while enabling rapid, remote-friendly access to device information and actions through MCP tools.

How to use

You connect your MCP client (for example Claude Desktop or another compliant host) to the ZigBee2MQTT MCP server to discover devices, inspect device details, and issue commands. Start by ensuring your ZigBee2MQTT setup is online and your MQTT broker is reachable. Once the MCP server is running, you can list devices, view device information, inspect available integrations, and send commands to devices. Use the provided tools to perform actions like finding devices by name, querying current device state, or retrieving documentation links for supported devices.

How to install

Prerequisites you need before installing the ZigBee2MQTT MCP server:

Node.js 20 or newer or Docker
Running ZigBee2MQTT installation
An MQTT broker (for example Mosquitto)

# Option 1: Docker (Recommended)
# 1. Clone and enter the project
git clone <repository-url>
cd zigbeeMCP

# 2. Create environment file
cp .env.example .env

# 3. Configure environment variables in .env
# MQTT_BROKER_URL, MQTT_USERNAME, MQTT_PASSWORD, MQTT_BASE_TOPIC, DB_PATH, LOG_LEVEL

# 4. Start the container
docker compose up -d

# 5. View logs
docker compose logs -f

# Option 2: Local Installation
# 1. Install dependencies
npm install

# 2. Compile TypeScript
npm run build

# 3. Start local server
npm start

Configuration and environment

The server uses a .env file to configure the MQTT connection, database path, and logging. Here is an example of the required settings:

MQTT_BROKER_URL=mqtt://192.168.1.100:1883
MQTT_USERNAME=your_user
MQTT_PASSWORD=your_password
MQTT_BASE_TOPIC=zigbee2mqtt
DB_PATH=/data/zigbee2mqtt.db

# Log Level: debug, info, warn, error, silent
LOG_LEVEL=error

Available tools

list_devices

Lists all ZigBee devices discovered through ZigBee2MQTT.

get_device_info

Shows detailed information about a specific device by name or IEEE address.

find_devices

Searches devices by name, model, or description.

get_device_state

Shows the current on/off state or other primary state of a device.

send_command

Sends a command to a device (e.g., turn on, set brightness).

find_by_capability

Finds all devices that support a given capability like on_off, brightness, temperature_sensor, etc.

get_integration_info

Provides integration guidance for tools like n8n for a specific device.

get_stats

Shows statistics about the ZigBee network and connected devices.

get_device_documentation

Provides links to official ZigBee2MQTT documentation for a device.

get_recent_devices

Lists devices added to the ZigBee network within the last N days.

Built by

VeilStrat

AI signals for GTM teams