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)
-
Clone repository
git clone <repository-url> cd zigbeeMCP -
Create environment file
cp .env.example .env -
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 -
Start container
docker compose up -d -
View logs
docker compose logs -f
Option 2: Local Installation
-
Install dependencies
npm install -
Compile TypeScript
npm run build -
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 addresscommand: 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/offbrightness- Dimmablecolor_temperature- Color temperature adjustablecolor- Color changeabletemperature_sensor- Temperature sensorhumidity_sensor- Humidity sensorcontact_sensor- Contact sensoroccupancy_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 addedlast_seen: Timestamp of last messageupdated_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
- Check MQTT broker URL in
.env - If broker runs on host, use
mqtt://host.docker.internal:1883 - Check firewall settings
No devices found
- Check if ZigBee2MQTT is running:
zigbee2mqtt/bridge/stateshould be "online" - Check base topic in
.env- must match ZigBee2MQTT config - 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 outputerror- Only errors (recommended for Claude Desktop)warn- Warnings + errorsinfo- Normal outputdebug- 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.