ZigBee2MQTT MCP Server

ZigBee2MQTT MCP 服务器

一个用于ZigBee2MQTT的模型上下文协议（MCP）服务器，为AI助手提供智能设备发现和控制功能。

🌐（万维网，互联网的象征） 具备远程功能！ 这个MCP服务器可以在一个（平台上/环境中）运行 远程服务器 （例如，您的MQTT代理运行的位置），并且您可以通过HTTP从您的Mac访问它。请参阅 REMOTE-SETUP.md 翻译为中文是：“远程设置指南.md” 或 “远程配置说明.md”（具体翻译可能根据上下文有所调整，但基本意思是“远程设置/配置的相关文件或指南”） 详情见下文！

部署选项

• 本地（标准输入输出）容器在您的Mac上运行，通过stdio进行访问
• 远程（HTTP/SSE）容器在服务器上运行，通过HTTP访问 REMOTE-SETUP.md 翻译为中文是：“远程设置指南/文件”（注：这里的“REMOTE-SETUP”通常指的是一个关于如何远程设置或配置某设备或系统的文件或指南，而“.md”是Markdown文件格式的扩展名，因此“REMOTE-SETUP.md”可以理解为“远程设置指南的Markdown文件”或简化为“远程设置指南”，具体翻译可能根据上下文有所调整）

概述

这台MCP服务器连接到您的MQTT代理，并自动分析通过ZigBee2MQTT连接的所有ZigBee设备。它学习每个设备的结构和功能，并通过MCP工具将这些信息提供给AI助手。

核心功能

• 🔍 智能模式发现自动学习您设备的结构和功能
• 💾 紧凑数据存储仅存储元数据和模式，不存储完整的消息历史
• 📚 Zigbee2MQTT 文档直接访问官方设备文档
• 🐳 准备就绪，可与Docker配合使用使用Docker Compose轻松部署
• 🌐 支持远程操作在服务器上运行，可通过HTTP/SSE从任何地方访问
• 🔒 安全可选的API密钥认证
• 🔌 保留消息使用MQTT保留消息以即时访问设备信息
• 🏠 家庭自动化非常适合n8n、Home Assistant及其他自动化工具

存储了什么？

✅ 表示“正确”或“确认”。 设备元数据 （名称、型号、制造商） ✅ 字段模式（或字段架构） （设备有哪些字段？数据类型是什么？） ✅ 能力 （可调亮度、变色、测温等） ✅ 当前状态 （仅显示最后一个值，无历史记录）

❌（这个符号在中文中通常表示“错误”或“不正确”的意思，但直接翻译时无法给出具体中文词汇，因为它是一个图形符号，所以保持原样或解释其含义即可。） 未存储完整的消息历史，基于时间的传感器数据

估计的数据库大小100台设备仅需约1-2MB（而非包含完整历史记录的GB！）

先决条件

• Node.js 20+ 或 Docker
• 运行ZigBee2MQTT安装程序
• MQTT 代理（例如，Mosquitto）

安装

选项1：Docker（推荐）

1. 克隆仓库

   git clone 
   cd zigbeeMCP

1. 创建环境文件

   cp .env.example .env

1. 配置 .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

1. 启动容器

   docker compose up -d

1. 查看日志

   docker compose logs -f

选项2：本地安装

1. 安装依赖项

   npm install

1. 编译TypeScript

   npm run build

1. 开始

   npm start

MCP配置

Claude Desktop（可译为“Claude桌面版”或根据上下文简化为“桌面版Claude”）

在Claude Desktop配置中添加以下内容（~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：

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

或者对于本地安装：

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

可用工具

MCP服务器提供以下工具：

1. list_devices

列出所有ZigBee设备。

示例：

Show me all my ZigBee devices

2. get_device_info

显示特定设备的详细信息。

参数：

• device设备友好名称或IEEE地址

示例：

Show me details for the living room lamp

3. find_devices

按名称、型号或描述搜索设备。

参数：

• query搜索词

示例：

Find all lamps in the living room

4. get_device_state

显示设备的当前状态。

参数：

• device设备友好名称或IEEE地址

示例：

Is the living room lamp on?

5. send_command

向设备发送命令。

参数：

• device设备友好名称或IEEE地址
• command以 JSON 对象形式表示的命令

示例：

Turn on the living room lamp
Set brightness to 50%

6. find_by_capability

查找具有特定功能的所有设备。

参数：

• capability能力类型（例如。， on_off， brightness， temperature_sensor)

示例：

Show all dimmable devices
Which devices can measure temperature?

通用能力：

• on_off - 可以打开/关闭
• brightness - 可调光
• color_temperature - 可调节色温
• color - 可变色
• temperature_sensor - 温度传感器
• humidity_sensor - 湿度传感器
• contact_sensor - 接触传感器
• occupancy_sensor - 运动传感器

7. get_integration_info

为n8n或其他工具提供集成信息。

参数：

• device设备友好名称或IEEE地址

示例：

How can I integrate the living room lamp into n8n?

8. get_stats

显示ZigBee网络的统计数据。

示例：

How many devices are connected?

9. get_device_documentation

为特定设备提供指向官方Zigbee2MQTT文档的链接。

参数：

• device设备友好名称或IEEE地址

示例：

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?

返回值：

• 在 zigbee2mqtt.io 上查看设备文档的链接
• 型号和供应商信息
• 该设备已知的功能
• 直接链接以搜索特定型号

10. get_recent_devices

列出在过去N天内添加到ZigBee网络的设备。

参数：

• days回溯的天数（默认：7）

示例：

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?

返回值：

• 天数
• 找到的设备数量
• 具有以下特征的设备列表：

- 名称、型号、制造商 - created_at设备添加时的时间戳 - last_seen最后一条消息的时间戳 - updated_at最后更新

注： 所有时间戳均为Unix时间戳（自1970年1月1日起的毫秒数）。

使用示例

使用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"

建筑学

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

故障排除

容器无法启动

# Check logs
docker compose logs

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

MQTT连接失败

1. 检查MQTT代理服务器URL .env
2. 如果代理运行在主机上，请使用 mqtt://host.docker.internal:1883
3. 检查防火墙设置

未找到设备

1. 检查ZigBee2MQTT是否正在运行： zigbee2mqtt/bridge/state 应该是“在线”
2. 检查基础主题在 .env - 必须与ZigBee2MQTT配置相匹配
3. 检查MQTT权限

数据库错误

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

Claude Desktop 中的日志过多

MCP服务器采用了一个可配置的日志记录系统：

调整至 .env：

# Minimal output (recommended)
LOG_LEVEL=error

# For debugging
LOG_LEVEL=debug

日志级别：

• silent - 无输出
• error - 仅显示错误（推荐用于Claude Desktop）
• warn - 警告 + 错误
• info - 正常输出
• debug - 所有细节

更改后：

docker compose restart

发展

本地开发

# Install dependencies
npm install

# TypeScript in watch mode
npm run watch

# In another terminal: start server
npm run dev

项目结构

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

许可证

麻省理工学院（MIT）

支持

如有关于问题或疑问，请在GitHub上创建一个议题。