ZigBee2MQTT MCP Server

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

🌐 Remote-Capable! This MCP server can run on a remote server (e.g., where your MQTT broker runs) and you can access it from your Mac via HTTP. See **REMOTE-SETUP.md** for details!

Deployment Options

Local (stdio): Container runs on your Mac, accessed via stdio
Remote (HTTP/SSE): Container runs on server, accessed via HTTP → **REMOTE-SETUP.md**

Overview

This MCP server connects to your MQTT broker and automatically analyzes all ZigBee devices connected via ZigBee2MQTT. It learns the structure and capabilities of each device and makes this information available to AI assistants through MCP tools.

Core Features

🔍 Intelligent Schema Discovery: Automatically learns the structure and capabilities of your devices
💾 Compact Data Storage: Stores only metadata and schemas, not complete message history
📚 Zigbee2MQTT Documentation: Direct access to official device documentation
🐳 Docker-Ready: Easy deployment with Docker Compose
🌐 Remote-Capable: Runs on server, access via HTTP/SSE from anywhere
🔒 Security: Optional API key authentication
🔌 Retained Messages: Uses MQTT retained messages for instant access to device information
🏠 Home Automation: Perfect for n8n, Home Assistant and other automation tools

What is Stored?

✅ Device Metadata (Name, model, manufacturer)

✅ Field Schemas (Which fields does a device have? What data types?)

✅ Capabilities (Can dim, change color, measure temperature, etc.)

✅ Current State (Only last value, no history)

❌ Not Stored: Complete message history, time-based sensor data

Estimated Database Size: ~1-2 MB for 100 devices (instead of GB with full history!)

Prerequisites

Node.js 20+ or Docker
Running ZigBee2MQTT installation
MQTT Broker (e.g., Mosquitto)

Installation

Option 1: Docker (Recommended)

1. Clone repository

bash

git clone 
   cd zigbeeMCP

2. Create environment file

bash

cp .env.example .env

3. Configure .env

env

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
   # Recommended: error (minimal output)
   LOG_LEVEL=error

4. Start container

bash

docker compose up -d

5. View logs

bash

docker compose logs -f

Option 2: Local Installation

1. Install dependencies

bash

npm install

2. Compile TypeScript

bash

npm run build

3. Start

bash

npm start

MCP Configuration

Claude Desktop

Add the following to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

json

{
  "mcpServers": {
    "zigbee2mqtt": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "zigbee2mqtt-mcp",
        "node",
        "dist/index.js"
      ]
    }
  }
}

Or for local installation:

json

{
  "mcpServers": {
    "zigbee2mqtt": {
      "command": "node",
      "args": ["/path/to/zigbeeMCP/dist/index.js"],
      "env": {
        "MQTT_BROKER_URL": "mqtt://localhost:1883",
        "MQTT_BASE_TOPIC": "zigbee2mqtt",
        "DB_PATH": "/path/to/zigbee2mqtt.db"
      }
    }
  }
}

Available Tools

The MCP server provides the following tools:

1. `list_devices`

Lists all ZigBee devices.

Example:

code

Show me all my ZigBee devices

2. `get_device_info`

Shows detailed information about a specific device.

Parameters:

device: Device friendly name or IEEE address

Example:

code

Show me details for the living room lamp

3. `find_devices`

Searches for devices by name, model, or description.

Parameters:

query: Search term

Example:

code

Find all lamps in the living room

4. `get_device_state`

Shows the current state of a device.

Parameters:

device: Device friendly name or IEEE address

Example:

code

Is the living room lamp on?

5. `send_command`

Sends a command to a device.

Parameters:

device: Device friendly name or IEEE address
command: Command as JSON object

Example:

code

Turn on the living room lamp
Set brightness to 50%

6. `find_by_capability`

Finds all devices with a specific capability.

Parameters:

capability: Capability type (e.g., on_off, brightness, temperature_sensor)

Example:

code

Show all dimmable devices
Which devices can measure temperature?

Common Capabilities:

on_off - Can be turned on/off
brightness - Dimmable
color_temperature - Color temperature adjustable
color - Color changeable
temperature_sensor - Temperature sensor
humidity_sensor - Humidity sensor
contact_sensor - Contact sensor
occupancy_sensor - Motion sensor

7. `get_integration_info`

Provides integration information for n8n or other tools.

Parameters:

device: Device friendly name or IEEE address

Example:

code

How can I integrate the living room lamp into n8n?

8. `get_stats`

Shows statistics about the ZigBee network.

Example:

code

How many devices are connected?

9. `get_device_documentation`

Provides links to official Zigbee2MQTT documentation for a specific device.

Parameters:

device: Device friendly name or IEEE address

Example:

code

Show me the documentation for my Philips Hue lamp
How can I best control the "living_room_lamp" device?
What can my IKEA TRADFRI switch do?

Returns:

Link to device documentation on zigbee2mqtt.io
Model and vendor information
Known capabilities of the device
Direct link to search for the specific model

10. `get_recent_devices`

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

Parameters:

days: Number of days to look back (default: 7)

Example:

code

Which devices were added in the last week?
Show me all new devices since yesterday
Which devices have I paired in the last 30 days?

Returns:

Number of days
Number of devices found
List of devices with:
Name, model, manufacturer
created_at: Timestamp when device was added
last_seen: Timestamp of last message
updated_at: Last update

Note: All timestamps are Unix timestamps (milliseconds since 1970-01-01).

Usage Examples

With Claude Desktop

code

User: "Is there a lamp in the living room?"
Claude: [Uses find_devices with query="living room"]
→ "Yes, I found 'living_room_ceiling_lamp' (Philips Hue White)"

User: "Turn it on"
Claude: [Uses send_command with {"state": "ON"}]
→ "The lamp has been turned on"

User: "How can I use this lamp in n8n?"
Claude: [Uses get_integration_info]
→ "You can use these MQTT topics:
   - Read: zigbee2mqtt/living_room_ceiling_lamp
   - Write: zigbee2mqtt/living_room_ceiling_lamp/set
   Example payload: {"state": "ON", "brightness": 200}"

User: "What can my IKEA TRADFRI switch do?"
Claude: [Uses get_device_documentation]
→ "Your IKEA TRADFRI switch (Model: E1743) supports:
   - Capabilities: button, battery
   - Documentation: https://www.zigbee2mqtt.io/supported-devices/#s=E1743
   - There you'll find all button events and MQTT payloads!"

User: "Which devices did I add in the last week?"
Claude: [Uses get_recent_devices with days=7]
→ "3 devices were added in the last 7 days:
   1. living_room_outlet (OSRAM Smart+ Plug) - 2 days ago
   2. bathroom_sensor (Aqara Temperature Sensor) - 5 days ago
   3. hallway_lamp (Philips Hue) - 6 days ago"

Architecture

code

┌─────────────────────┐
│   AI Assistant      │
│   (Claude Desktop)  │
└──────────┬──────────┘
           │ MCP Protocol (stdio)
┌──────────▼──────────┐
│   MCP Server        │
│   - Tools Handler   │
│   - Response Gen.   │
└──────────┬──────────┘
           │
┌──────────▼──────────┐      ┌──────────────────┐
│  SQLite Database    │      │  MQTT Listener   │
│  - Devices          │      │  - Subscribe All │
│  - Fields           │◄─────┤  - Process Msgs  │
│  - Capabilities     │      │  - Discovery     │
│  - Current State    │      └────────┬─────────┘
└─────────────────────┘               │
                                      │
                              ┌───────▼────────┐
                              │  MQTT Broker   │
                              │  (Mosquitto)   │
                              └───────┬────────┘
                                      │
                              ┌───────▼────────┐
                              │  ZigBee2MQTT   │
                              │  - ZigBee Net  │
                              │  - Devices     │
                              └────────────────┘

Troubleshooting

Container won't start

bash

# Check logs
docker compose logs

# Rebuild container
docker compose down
docker compose build --no-cache
docker compose up -d

MQTT connection fails

1. Check MQTT broker URL in .env

2. If broker runs on host, use mqtt://host.docker.internal:1883

3. Check firewall settings

No devices found

1. Check if ZigBee2MQTT is running: zigbee2mqtt/bridge/state should be "online"

2. Check base topic in .env - must match ZigBee2MQTT config

3. Check MQTT permissions

Database errors

bash

# Reset database
docker compose down
rm -rf data/
docker compose up -d

Too many logs in Claude Desktop

The MCP server uses a configurable logging system:

**Adjust in .env:**

env

# Minimal output (recommended)
LOG_LEVEL=error

# For debugging
LOG_LEVEL=debug

Log Levels:

silent - No output
error - Only errors (recommended for Claude Desktop)
warn - Warnings + errors
info - Normal output
debug - All details

After changes:

bash

docker compose restart

Development

Local Development

bash

# Install dependencies
npm install

# TypeScript in watch mode
npm run watch

# In another terminal: start server
npm run dev

Project Structure

code

src/
├── index.ts              # Main entry point
├── types.ts              # TypeScript definitions
├── database.ts           # SQLite database logic
├── mqtt-listener.ts      # MQTT client & message handler
├── schema-discovery.ts   # Schema discovery engine
└── mcp-server.ts         # MCP server & tools

License

MIT

Support

For questions or issues, please create an issue on GitHub.

Mcp2zigbee2mqtt

Documentation

ZigBee2MQTT MCP Server

Deployment Options

Overview

Core Features

What is Stored?

Prerequisites

Installation

Option 1: Docker (Recommended)

Option 2: Local Installation

MCP Configuration

Claude Desktop

Available Tools

1. list_devices

2. get_device_info

3. find_devices

4. get_device_state

5. send_command

6. find_by_capability

7. get_integration_info

8. get_stats

9. get_device_documentation

10. get_recent_devices

Usage Examples

With Claude Desktop

Architecture

Troubleshooting

Container won't start

MQTT connection fails

No devices found

Database errors

Too many logs in Claude Desktop

Development

Local Development

Project Structure

License

Support

Similar MCP

Mcp Ipfs

Mcp Open Library

Metmuseum Mcp

Anilist Mcp

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Mcp Ipfs

Mcp Open Library

Metmuseum Mcp

Anilist Mcp

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

1. `list_devices`

2. `get_device_info`

3. `find_devices`

4. `get_device_state`

5. `send_command`

6. `find_by_capability`

7. `get_integration_info`

8. `get_stats`

9. `get_device_documentation`

10. `get_recent_devices`