zigbee2mqtt-mcp

zigbee2mqtt-mcp

一个用于管理 Zigbee2MQTT 部署的 Model Context Protocol 服务。

大多数 Zigbee 集成已经能让助手打开灯具。本服务面向更底层的管理工作：网状网络健康状况、弱连接、反复重新入网的设备、电池电量过低的设备、固件更新、配对、绑定、上报间隔和设备选项——这些通常需要打开 Zigbee2MQTT 前端才能处理。

它直接与 Zigbee2MQTT 的 MQTT bridge API 通信，因此无论你使用 Home Assistant、Node-RED、openHAB，还是完全不使用这些工具，都能正常工作。已针对 Zigbee2MQTT 2.x 测试；多个工具依赖仅在该版本中存在的 bridge 端点，包括 bridge/health、device/binds/clear 和 OTA 调度主题。

为什么要开发这个项目

如果你已经运行 Home Assistant，Zigbee 设备就会在其中公开，助手也能控制它们。但 Home Assistant 不会公开 bridge 本身：链路质量、网状网络拓扑、采访状态、OTA 可用性、permit_join、设备选项、绑定和上报配置。本服务正好填补了这一空缺。

设计

• 无数据库。 Zigbee2MQTT 会将 bridge 主题作为保留消息发布，因此新订阅能在几百毫秒内获得完整信息。本服务只在内存中保留每个主题的最新负载。
• 无需守护进程。 纯 stdio。它随 MCP 会话启动，并在会话结束时退出。
• 请求关联。 每个 bridge/request/* 都带有 transaction ID，并与对应的 bridge/response/* 匹配，因此并发调用不会彼此串线。
• 分级写入。 破坏性操作必须同时启用写入模式，并明确提供 confirm 参数。

安装

需要 Node.js 22 或更高版本，并且能够访问 Zigbee2MQTT 使用的 MQTT broker。

npx zigbee2mqtt-mcp

VS Code / GitHub Copilot

添加到你的 MCP 配置中：

{
  "servers": {
    "zigbee2mqtt": {
      "command": "npx",
      "args": ["-y", "zigbee2mqtt-mcp"],
      "env": {
        "Z2M_MQTT_URL": "mqtt://192.168.1.10:1883",
        "Z2M_MQTT_USERNAME": "mqtt",
        "Z2M_MQTT_PASSWORD": "${input:z2mPassword}"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "zigbee2mqtt": {
      "command": "npx",
      "args": ["-y", "zigbee2mqtt-mcp"],
      "env": {
        "Z2M_MQTT_URL": "mqtt://192.168.1.10:1883"
      }
    }
  }
}

将 Z2M_MQTT_URL 指向你的 MQTT broker，而不是 Zigbee2MQTT 前端端口。如果 Zigbee2MQTT 的 configuration.yaml 中写的是 mqtt.server: mqtt://192.168.1.10:1883，请原样使用该值。

使用企业 npm 代理？如果 npm config get registry 返回的不是 https://registry.npmjs.org/，代理的上游源可能没有此软件包。请在 args 中添加明确的覆盖项，而不要更改全局 registry： "args": ["-y", "--registry", "https://registry.npmjs.org/", "zigbee2mqtt-mcp"]

配置

变量	默认值	用途
Z2M_MQTT_URL	必填	Broker URL。mqtt://、mqtts://、ws://、wss://
Z2M_MQTT_USERNAME / Z2M_MQTT_PASSWORD	–	Broker 凭据
Z2M_BASE_TOPIC	zigbee2mqtt	必须与 mqtt.base_topic 一致
Z2M_MQTT_CLIENT_ID	zigbee2mqtt-mcp-<pid>	如果 Broker 要求固定的客户端 ID，请覆盖此值
Z2M_WRITE_MODE	safe	off、safe 或 full
Z2M_LOG_LEVEL	error	在 stderr 上输出诊断信息
Z2M_WEAK_LINK_THRESHOLD	30	低于此值的链路质量将被标记
Z2M_LOW_BATTERY_THRESHOLD	20	低于此值的电池电量百分比将被标记
Z2M_STALE_HOURS	24	设备静默多少小时后视为陈旧
Z2M_CONNECT_TIMEOUT_MS	10000	Broker 连接超时时间
Z2M_REQUEST_TIMEOUT_MS	15000	桥接请求的默认超时时间
Z2M_MQTT_REJECT_UNAUTHORIZED	true	使用自签名 TLS 时设为 false
Z2M_MQTT_CA / _CERT / _KEY	–	TLS 材料的路径

写入模式

高于当前级别的工具完全不会注册，因此模型无法调用它们。

模式	开放的工具
off	只读工具
safe	默认。 读取及非破坏性写入：配对、选项、重命名、配置、访谈、绑定、上报、群组、状态
full	所有工具，包括移除设备、OTA 刷写、Touchlink 和重启桥接

不可逆工具（z2m_remove_device、z2m_ota_update、z2m_touchlink、z2m_restart_bridge、z2m_set_bridge_options）每次调用时还必须提供 confirm: true。有三个 safe 工具会减少状态，而不只是增加状态，因此标注为破坏性工具：z2m_rename_device、z2m_manage_group 和 z2m_bind。它们会减少状态的操作也必须提供 confirm: true——z2m_manage_group（remove、remove_all_members）和 z2m_bind（clear）。z2m_rename_device 被标注为破坏性工具，因为这会导致引用旧名称的内容失效；但它不要求确认，因为改回原名即可恢复。

每个工具还会声明 MCP 工具注解，以便客户端决定哪些操作可以无需提示直接运行：

注解	此处含义
readOnlyHint: true	九个只读工具。它们绝不会更改网络。
destructiveHint: true	z2m_remove_device、z2m_ota_update、z2m_touchlink、z2m_restart_bridge、z2m_set_bridge_options，以及 z2m_rename_device、z2m_manage_group 和 z2m_bind
idempotentHint	若重复调用不会产生额外影响，则为 true
openWorldHint: true	始终为 true——每个工具都会访问实时 Zigbee 网络

注解描述的是工具，而非级别：safe 工具仍可能具有破坏性。级别决定注册哪些工具，注解则告知客户端需要就哪些事项征求确认。

仅当你需要时，才选择启用破坏性级别：

"env": { "Z2M_WRITE_MODE": "full" }

工具

读取

工具	用途
z2m_connection_status	Broker 可达性、TLS 状况和缓存的消息数量——即使尚未配置任何内容，也会返回状态而非抛出错误
z2m_bridge_info	版本、协调器、信道、PAN ID、permit_join、restart_required、运行时统计信息
z2m_list_devices	按类型、可用性、链路质量、电池电量、待处理更新筛选和排序设备
z2m_get_device	暴露项、可设置选项、端点、绑定、已配置的上报项、当前状态
z2m_health_report	一次调用即可审计整个设备群
z2m_network_map	网状网络拓扑，包含父节点、深度、链路质量和孤立节点检测
z2m_list_groups	群组、成员和场景
z2m_get_logs	桥接日志和生命周期事件，可读取缓冲日志或实时监控
z2m_coordinator_check	协调器内存中缺失的路由器（仅限 Texas Instruments 适配器）

安全写入

z2m_check_updates、z2m_permit_join、z2m_set_device_options、z2m_rename_device、z2m_configure_device、z2m_interview_device、z2m_set_state、z2m_manage_group、z2m_bind、z2m_configure_reporting

完全写入

z2m_remove_device、z2m_ota_update、z2m_restart_bridge、z2m_set_bridge_options、z2m_touchlink

数据可用性注意事项

某些字段取决于你的 Zigbee2MQTT 配置。服务会检测哪些数据可用，并告知你，而不是默默返回空结果。

字段	需要	如果缺失
last_seen	将 advanced.last_seen 设为例如 ISO_8601（默认值为 disable）	跳过过期检查，并返回提示
availability	availability.enabled: true	跳过离线检测，并返回提示
linkquality、battery、update	实时设备流量 — Zigbee2MQTT 不会保留设备状态主题	传入 collect_seconds 以短暂监听，或使用 z2m_network_map 获取权威链路质量数据
z2m_coordinator_check	支持协调器备份的适配器（TI zStack、Silicon Labs EmberZNet；不包括 deCONZ 或 ZiGate）	对不支持的适配器返回错误；z2m_bridge_info 会说明预期要求

安全说明

• Broker URL 可能包含凭据（mqtt://user:pass@host）。无论在何处回显给模型或写入日志，凭据都会被隐藏；MQTT 客户端的错误文本也会在离开进程前经过清理。Zigbee2MQTT 会在启动时记录自己的 broker URL，因此由 z2m_get_logs 转发的日志行也会经过清理。
• safe 模式可以通过 z2m_set_state 控制网状网络中的任何设备，包括门锁、阀门和警报器。如果你在意这一点，请使用 off。
• z2m_permit_join 会在设定的时间内向附近的任何 Zigbee 设备开放网络。它属于 safe 模式，因为这是常规且可逆的操作，但它仍是一条安全边界。

示例提示词

• “我的 Zigbee 网络运行正常吗？”
• “哪些设备的信号最弱？”
• “哪些电池需要更换？”
• “有可用的固件更新吗？”
• “通过厨房路由器开放网络两分钟，以便配对。”
• “这个传感器停止上报温度了——修复它。”
• “将走廊遥控器绑定到走廊灯，这样即使网桥离线也能使用。”

开发

npm install
npm run build
npm run watch

# Unit tests. No broker required; they run on every push across Node 22 and 24.
npm test

# Manual smoke test against a real instance
Z2M_MQTT_URL=mqtt://192.168.1.10:1883 node scripts/smoke.mjs
Z2M_MQTT_URL=mqtt://192.168.1.10:1883 node scripts/smoke.mjs z2m_list_devices '{"only_problems":true}'

# Sequential read-after-write test. Renames a device and creates a group, then
# restores both, including on failure. Set Z2M_TEST_DEVICE to pick the device,
# or ROUNDTRIP_GROUPS_ONLY=1 to skip the rename.
Z2M_MQTT_URL=mqtt://192.168.1.10:1883 node scripts/roundtrip.mjs

请注意，MCP 服务可能会并发收到请求。测试请求顺序时，请先等待每个响应，再发送下一个请求，就像 roundtrip.mjs 所做的那样——一次传入多个请求会产生误导性结果。

单元测试涵盖健康状态分类、能力检测、主题路由、写入模式限制和配置解析。它们经过专门设计，不依赖 Broker；因此，任何需要实时网状网络的操作都应放在 scripts/ 中。

测试通过只能证明测试已运行，因此 scripts/mutate.mjs 会一次更改一处源代码，并检查测试套件是否能发现每项更改：

node scripts/mutate.mjs          # every mutant
node scripts/mutate.mjs redact   # only mutants whose name matches

仍能通过测试的变异说明某项行为实际上没有受到测试覆盖，并会以非零状态码退出。添加修复时，也应一并添加对应的变异测试，确保修复不会被破坏。

发布由标签驱动：运行 npm version <patch|minor|major>，然后运行 git push --follow-tags。CI 会使用来源证明发布到 npm，根据标签重写 server.json 中的版本，并发布到 MCP Registry，随后创建 GitHub release。因此，提交在 server.json 中的 version 并非权威版本——标签才是。

安全

此服务可以从网络中移除设备并刷写固件。这两项操作都不可逆，OTA 失败还可能导致硬件变砖。这些工具位于 full 级别，默认未启用——你必须通过 Z2M_WRITE_MODE=full 主动启用。Broker 凭据从环境中读取，绝不会写入日志。

状态

早期版本。基于 Zigbee2MQTT 2.12.x，在包含 50 台设备的 EmberZNet 环境中开发并测试。其他适配器（Texas Instruments、deCONZ/ConBee、zStack）、TLS 和 WebSocket 代理以及大型环境均未经验证。非常欢迎提交 Bug 报告和拉取请求——请附上 z2m_bridge_info 中的适配器类型和 Zigbee2MQTT 版本。

许可证

MIT