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

Or for local installation:

Available Tools

The MCP server provides the following tools:

1. list_devices

Lists all ZigBee devices.

Example:

2. get_device_info

Shows detailed information about a specific device.

Parameters:

• device: Device friendly name or IEEE address

Example:

3. find_devices

Searches for devices by name, model, or description.

Parameters:

• query: Search term

Example:

4. get_device_state

Shows the current state of a device.

Parameters:

• device: Device friendly name or IEEE address

Example:

5. send_command

Sends a command to a device.

Parameters:

• device: Device friendly name or IEEE address

• command: Command as JSON object

Example:

6. find_by_capability

Finds all devices with a specific capability.

Parameters:

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

Example:

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:

8. get_stats

Shows statistics about the ZigBee network.

Example:

9. get_device_documentation

Provides links to official Zigbee2MQTT documentation for a specific device.

Parameters:

• device: Device friendly name or IEEE address

Example:

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:

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

Architecture

Troubleshooting

Container won't start

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

Too many logs in Claude Desktop

The MCP server uses a configurable logging system:

Adjust in

Log Levels:

• silent - No output

• error - Only errors (recommended for Claude Desktop)

• warn - Warnings + errors

• info - Normal output

• debug - All details

After changes:

Development

Local Development

Project Structure

License

MIT

Support

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