内容
bee2MQTT
一款适用于 [Z2MQTT](https://www.zigbee2mqtt.io [MCP](httpscontextprotocol.io) 服务器。它允许LLM（或任何MCP客户端）列出和检查您的Zigbee设备和更改其状态，并Zigbee2MQTT前端Websocket API** 管理网它不需要直接访问您的MQTT代理。
## 为什么使用前端
Zigbee2MQTT的前端在`/api`处暴露了一个websocket，它将MQTT流量代理为JSON消息（已基本主题）。与其直接与MQTT代理通信，这意味着：
- **无需代理依赖** - 即使您不在网络上公开MQTT，也能正常工作。
- **单个HTTPS端点** - 重用现有的反向代理/TLS。
- **身份验证就绪** - 支持前端`auth_token`，当您启用它时。
更改网桥的请求（`bridge/request/*`）与其`bridge/response/*`回复通过事务ID关联，每个调用都有超时。保留的设备快照在连接时缓存，因此读取是即时的，如果连接断开，则自动重新连接（重新初始化缓存）。
## 工具列表
**读取**
| 工具 | 描述 |
|------|-------------|
| `connection_status` | Websocket健康状况 + 缓存准备就绪 |
| `list_devices` | 所有设备（紧凑摘要或`detailed=true`） |
| `find_devices` | 按名称/型号/供应商/地址搜索 |
| `get_device` | 设备的完整定义/元数据 |
| `get_device_state` | 当前缓存状态（+可选`refresh`） |
| `list_groups` | 所有组及其成员 |
| `get_bridge_info` | 版本、协调器、配置、允许加入状态 |
| `get_bridge_state` / `get_bridge_health` | 网桥在线状态 / 健康指标 |
| `get_network_map` | 扫描并返回Zigbee网状网络地图 |
**控制**
| 工具 | 描述 |
|------|-------------|
| `set_device_state` | 设置状态 — `{"state":"ON"}`，亮度，颜色，覆盖位置，… |
| `ota_check` | 检查固件更新 |
| `permit_join`* | 允许/拒绝新设备加入 |
| `rename_device`* | 重命名设备 |
| `remove_device`* | 取消设备配对 |
| `set_device_options`* / `configure_device`* | 设备特定选项 / 重新配置 |
| `ota_update`* | 执行固件更新 |
| `create_group`* / `remove_group`* / `group_add_member`* / `group_remove_member`* | 组管理 |
\* 保护：除非`Z2M_ALLOW_DESTRUCTIVE=true`，否则禁用。读取和`set_device_state`始终可用。
## 配置
所有配置均通过环境变量（参见 [`.env.example`](.env.example)）：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `Z2M_FRONTEND_URL` | `http://localhost:8080` | Zigbee2MQTT前端的基本URL。从中派生`ws(s)://…/api` |
| `Z2M_AUTH_TOKEN` | *(空)* | 前端`auth_token`，追加为`?token=…` |
| `Z2M_TLS_INSECURE` | `false` | 跳过`wss://`的TLS验证（自签名） |
| `Z2M_REQUEST_TIMEOUT` | `15` | 等待`bridge/response`的秒数 |
| `Z2M_CONNECT_TIMEOUT` | `20` | 启动时等待初始快照的秒数 |
| `Z2M_ALLOW_DESTRUCTIVE` | `false` | 启用受保护的管理工具 |
| `MCP_TRANSPORT` | `http` | `http`（可流式HTTP）或`stdio` |
| `MCP_HOST` / `MCP_PORT` / `MCP_PATH` | `0.0.0.0` / `8080mcp` | HTTP 路径 |
| `M_PROTECTION` |` | DNS重绑定主机保护：`false`，`或`auto` `MCP_ALLOWED_HOSTS` | `*.strant.casa,localhost,127.0.0.1` | 主机允许列表（在保护开启时使用） |
| `MCP_LOG_LEVEL` | `INFO` | 日志级别 |
## 运行
### Docker（推荐）
```bash
docker run -d --name zigbee2mqtt-mcp -p 8080 \
-e Z2M_FRONTEND_URL=https://zigmqtt.example.com \
.io/loryanstrzigbee2mqtt-mcp```
MCP端点位于`http://<host>:808cp`。
或使用Compose复制`.env.example`env`，编辑它，然后：
```bash
docker compose
```
### 本地 3.11+）
```bash
pip install .
Z2M_FRONTEND_URL=https://zigbee2mqtt.example.com python -m zigbee2mqtt_mcp
```
### stdio（本地客户端，例如Claude Desktopjson
{
"Servers": {
"2mqtt": {
" "python",
" ["-m", "zigmqtt_mcp"],
": {
"MCP_TRANSPORT": "stdio",
"Z2M_FRONTEND_URL": "https://zigbee2mqtt.example.com"
}
}
}
}
```
## 开发
```bash
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest
```
## 安全
此服务器公开了对您的Zigbee网络的控制。将其绑定到受信任的网络（LAN/VPN）或身份验证代理，保持`Z2M_ALLOW_DESTRUCTIVE=false`，除非您需要管理工具，并且永远不要提交已填充的`.env`。参见 [SECURITY.md](SECURITY.md)。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
