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

   git clone <repository-url>
   cd zigbeeMCP
   

2. Create environment file

   cp .env.example .env
   

3. Configure .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

   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

   npm start
   

MCP Configuration

Claude Desktop

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

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

Or for local installation:

{
  "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:

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:

Show me details for the living room lamp

3. find_devices

Searches for devices by name, model, or description.

Parameters:

• query: Search term

Example:

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:

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:

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:

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:

How can I integrate the living room lamp into n8n?

8. get_stats

Shows statistics about the ZigBee network.

Example:

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:

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:

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

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

┌─────────────────────┐
│   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

# 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

# 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:

# 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:

docker compose restart

Development

Local Development

# Install dependencies
npm install

# TypeScript in watch mode
npm run watch

# In another terminal: start server
npm run dev

Project Structure

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.