内容
# 本地家居设备MCP服务器
[](https://github.com/paulomac1000/local-home-devices-mcp/actions/workflows/ci.yml)
[](https://github.com/paulomac1000/local-home-devices-mcp/actions/workflows/publish.yml)
[](https://www.python.org/)
[](LICENSE)
MCP（模型上下文协议）服务器，用于物联网设备管理。使AI助手（Claude Desktop，LibreChat，Cline）能够在本地网络上发现和控制OpenBK（OpenBeken），Tasmota和Tuya设备。
## 需求
- Docker（推荐）或Python 3.11+（用于本地使用）
- MQTT代理（可选 - 仅在需要MQTT工具时需要）
- 本地网络上的OpenBK或Tasmota设备
- Tuya设备（WiFi型号；可选 - 需要Tuya云API凭证）
- **nmap** - 在Docker中自动安装；本地使用时，通过`apt-get install nmap`安装（可能需要root/sudo权限）
**网络注意事项：** Docker使用`--network host`模式访问本地网络中的IoT设备。这是nmap扫描和与设备直接进行HTTP通信所必需的。
## 快速开始
### 1. 配置
```bash
cp .env.example .env
# 编辑.env文件，填写MQTT_BROKER和网络范围
```
### 2. 使用Docker运行
**选项A -- 使用GitHub容器注册表中的预构建镜像：**
```bash
docker run -d \
--name local-home-devices-mcp \
--network host \
-e MQTT_BROKER=192.168.1.100 \
-e START_IP=192.168.1.1 \
-e END_IP=192.168.1.254 \
-v local-home-devices-data:/app/data \
ghcr.io/paulomac1000/local-home-devices-mcp:latest
```
**选项B -- 使用docker compose：**
```bash
cp .env.example .env
# 编辑.env文件，填写您的设置
docker compose up -d
```
**选项C -- 本地构建：**
```bash
docker build -t local-home-devices-mcp .
docker run -d \
--network host \
-e MQTT_BROKER=192.168.1.100 \
-e START_IP=192.168.1.1 \
-e END_IP=192.168.1.254 \
-v local-home-devices-data:/app/data \
local-home-devices-mcp
```
### 3. 本地运行（Python 3.11+）
```bash
pip install -r requirements.txt
MQTT_BROKER=192.168.1.100 START_IP=192.168.1.1 END_IP=192.168.1.254 python server.py
```
## 架构
| 端口 | 协议 | 目的 | 端点 |
|------|----------|---------|----------|
| 9100 | HTTP | 健康检查 | `GET /health` |
| 9101 | SSE | MCP传输 | `/sse`, `/messages` |
| 9102 | HTTP | REST API | `/api/*` |
### 验证
```bash
# 健康检查
curl http://localhost:9100/health
# 列出所有MCP工具
curl http://localhost:9102/api/tools
# 通过REST API调用工具
curl -X POST http://localhost:9102/api/tools/iot_list_devices \
-H "Content-Type: application/json" \
-d '{}'
```
## 可用工具
### 设备发现
所有只读操作 - 不修改设备状态。
| 工具 | 风险 | 描述 |
|------|------|-------------|
| `iot_discover_devices` | [READ] | 扫描本地网络中的OpenBK和Tasmota设备 |
| `iot_list_devices` | [READ] | 从缓存中列出所有已发现的设备 |
| `iot_check_device` | [READ] | 快速连接性和状态检查特定IP地址 |
| `iot_find_device_by_name` | [READ] | 按友好名称查找设备 |
### 设备信息
所有只读操作 - 不修改设备状态。
| 工具 | 风险 | 描述 |
|------|------|-------------|
| `iot_get_device_info` | [READ] | 完整的设备信息（名称，固件，芯片类型等） |
| `iot_get_device_power` | [READ] | 特定通道的当前电源状态 |
| `iot_get_wifi_config` | [READ] | WiFi SSID，RSSI信号强度，MAC，IP地址 |
### 设备控制
| 工具 | 风险 | 描述 |
|------|------|-------------|
| `iot_set_power` | [WRITE] | 打开，关闭或切换通道 |
| `iot_set_brightness` | [WRITE] | 设置亮度级别（0-100％） |
| `iot_restart_device` | [DESTRUCTIVE] | 重启设备（暂时断开连接） |
### 设备配置
| 工具 | 风险 | 描述 |
|------|------|-------------|
| `iot_set_flags` | [WRITE] | 设置设备配置标志为位域（OpenBK /cfg_generic，Tasmota SetOption） |
| `iot_set_name` | [WRITE] | 设置设备短名称和全名称（OpenBK via /cfg_name） |
| `iot_configure_mqtt` | [WRITE] | 配置MQTT代理连接（OpenBK via /cfg_mqtt_set） |
| `iot_set_gpio` | [WRITE] | 配置GPIO引脚角色和通道（OpenBK via /cfg_pins） |
| `iot_execute_command` | [DESTRUCTIVE] | 执行原始/cm？cmnd =命令，具有阻止命令安全性 |
| `iot_start_ha_discovery` | [WRITE] | 触发Home Assistant MQTT发现（OpenBK via /ha_discovery） |
| `iot_get_full_info` | [READ] | 增强设备信息：MAC，版本，标志，MQTT，WiFi（OpenBK和Tasmota） |
### 自省
| 工具 | 风险 | 描述 |
|------|------|-------------|
| `describe_iot_capabilities` | [READ] | 描述所有IoT工具，清单和传输 |
### MQTT集成
| 工具 | 风险 | 描述 |
|------|------|-------------|
| `iot_mqtt_publish` | [WRITE] | 通过MQTT发布命令 |
| `iot_mqtt_get_state` | [READ] | 从MQTT代理获取设备状态 |
| `iot_mqtt_build_command_topic` | [READ] | 为设备构建MQTT命令主题 |
### OpenHASP面板
| 工具 | 风险 | 描述 |
|------|------|-------------|
| `openhasp_detect` | [READ] | 检查IP地址是否为OpenHASP面板 |
| `openhasp_status` | [READ] | 完整的面板状态：版本，背光，对象，堆，WiFi |
| `openhasp_check_backlight` | [READ] | 分析背光常见问题 |
| `openhasp_get_config` | [READ] | 从面板获取完整的config.json |
| `openhasp_get_pages` | [READ] | 获取pages.jsonl，包含对象/页面计数 |
| `openhasp_screenshot` | [READ] | 捕获和下载screenshot.bmp |
| `openhasp_download_file` | [READ] | 从面板下载任何配置文件/命令文件 |
| `openhasp_upload_file` | [WRITE] | 通过POST /edit上传文件 |
| `openhasp_ota_update` | [DESTRUCTIVE] | 通过URL进行OTA固件更新 |
| `openhasp_page_set` | [WRITE] | 导航到特定页面 |
| `openhasp_jsonl_send` | [WRITE] | 发送JSONL以创建/修改UI对象 |
| `openhasp_telnet` | [WRITE] | 发送原始Telnet命令（原始TCP，无telnetlib） |
| `openhasp_backlight_set` | [WRITE] | 设置背光状态和亮度 |
| `openhasp_config_set` | [WRITE] | 通过Telnet配置/ GUI进行运行时配置 |
| `openhasp_idle_reset` | [WRITE] | 重置空闲计时器以唤醒屏幕 |
| `openhasp_restart` | [DESTRUCTIVE] | 重启面板 |
| `openhasp_factory_reset` | [DESTRUCTIVE] | 工厂重置（仅EEPROM，文件存活） |
| `openhasp_validate_config` | [READ] | 验证配置是否存在常见问题 |
| `openhasp_health` | [READ] | 综合健康评分0-100 |
| `openhasp_hardware_test` | [WRITE] | 自动诊断序列 |
### 海康威视门铃
| 工具 | 风险 | 描述 |
|------|------|-------------|
| `hikvision_container_status` | [READ] | 获取Docker容器运行状态和健康状态 |
| `hikvision_container_logs` | [READ] | 获取最近的容器日志（VMD事件，调用，错误） |
| `hikvision_device_info` | [READ] | 通过ISAPI获取门铃设备元数据 |
| `hikvision_check_vmd` | [READ] | 检查VMD运动事件 - ISAPI健康检查 |
| `hikvision_take_snapshot` | [READ] | 从门铃摄像头捕获JPEG快照 |
| `hikvision_get_motion_config` | [READ] | 获取VMD运动检测配置 |
| `hikvision_get_event_config` | [READ] | 获取ISAPI事件触发配置 |
| `hikvision_get_alarm_server` | [READ] | 获取HTTP通知主机（报警服务器）配置 |
| `hikvision_isapi_health` | [READ] | 综合健康检查（容器+VMD+调用事件） |
| `hikvision_pipeline_diagnose` | [READ] | 完整的管道跟踪（容器到ISAPI到事件到MQTT到快照） |
| `hikvision_open_gate` | [WRITE] | 触发电锁继电器打开门 |
| `hikvision_set_motion_detection` | [WRITE] | 启用/禁用VMD或调整灵敏度（写入保护） |
| `hikvision_snapshot_to_file` | [WRITE] | 捕获JPEG并直接保存到磁盘（写入保护） |
| `hikvision_restart_container` | [DESTRUCTIVE] | 重启Docker容器 |
> **注意**：标记为`[CONTAINER]`的工具需要`hikvision-doorbell`Docker容器
> 并访问`/var/run/docker.sock`。仅ISAPI的工具适用于任何可以通过HTTP摘要身份验证访问的海康威视门铃。
## 配置
所有配置均通过环境变量进行。有关完整的模板，请参见`.env.example`。
### MQTT工具所需（否则可选）
| 变量 | 描述 | 示例 |
|----------|-------------|---------|
| `MQTT_BROKER` | MQTT代理IP地址 | `192.168.1.100` |
> **提示：** 没有MQTT代理，设备发现和HTTP控制仍然有效。仅当您需要基于MQTT的工具（`iot_mqtt_publish`，`iot_mqtt_get_state`等）时，请设置`MQTT_BROKER`。
### 网络扫描
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `START_IP` | `192.168.1.1` | 扫描范围的第一个IP地址 |
| `END_IP` | `192.168.1.254` | 扫描范围的最后一个IP地址 |
| `NETWORK_RANGE` | `192.168.1.0/24` | nmap扫描的CIDR范围（如果设置，则覆盖START_IP/END_IP） |
### 可选
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ENABLE_WRITE_OPERATIONS` | `0` | 设置为`1`以启用写入/破坏性工具（set_power，restart等） |
| `MQTT_PORT` | `1883` | MQTT代理端口 |
| `MQTT_USER` | -- | MQTT用户名 |
| `MQTT_PASSWORD` | -- | MQTT密码 |
| `MCP_SSE_PORT` | `9101` | MCP SSE传输端口 |
| `REST_API_PORT` | `9102` | REST API端口 |
## 项目结构
- `tools/constants.py` - 所有共享配置默认值（工具文件中无硬编码IP地址）
- `tools/validators.py` - 工具参数输入验证
- `tools/iot_control.py` - 电源/亮度/重启/WiFi控制（4个工具）
- `tools/iot_devices.py` - 设备信息/电源状态（2个工具）
- `tools/iot_discovery.py` - 网络扫描/设备发现/缓存（4个工具）
- `tools/iot_mqtt.py` - MQTT发布/状态/主题（3个工具）
- `tools/iot_meta.py` - 能力自省，清单和传输（1个工具）
- `tools/iot_tuya.py` - Tuya设备云+本地控制+诊断（10个工具）
- `tools/iot_openhasp.py` - OpenHASP面板控制，诊断，Telnet（20个工具）
- `tools/openhasp/` - OpenHASP HTTP，Telnet，诊断助手
- `tools/iot_config.py` - 设备配置工具（7个工具）
- `tools/iot_hikvision.py` - 海康威视门铃工具（14个工具）
- `tools/hikvision/` - ISAPI HTTP客户端，Docker套接字助手
- `tools/http_session.py` - 通用IoT设备HTTP客户端模块
## 支持的设备
### OpenBK（OpenBeken）
- **芯片**：BK7231N，BK7231T，XR809，BL602
- **设备**：灯，开关，窗帘，传感器
- **检测**：HTTP `GET /index`返回包含`"openbeken"`的HTML
### Tasmota
- **芯片**：ESP8266，ESP32
- **设备**：灯，开关，传感器，风扇，插头
- **检测**：HTTP `GET /cm?cmnd=Status`返回具有`"Status"`键的JSON
### Tuya
- **芯片**：ESP8266，ESP32，BK7231N/T（因供应商而异）
- **设备**：吸尘器，电 kettle，水阀，传感器，网关
- **检测**：本地网络上打开TCP端口6668
- **要求**：Tuya云API凭证（Access ID，Access Secret）用于本地密钥检索
- **协议**：通过`tinytuya`库进行加密TCP/UDP，云API备用
### OpenHASP
- **芯片**：ESP32（WT32-SC01，WT32-SC01 Plus，ESP32-S3）
- **设备**：触摸屏显示器，壁挂式仪表盘，控制面板
- **检测**：HTTP `GET /config.json`返回具有`"hasp"`键的JSON
- **协议**：用于配置/文件的HTTP API +用于控制的原始TCP Telnet（不是telnetlib）
- **Telnet**：使用原始TCP套接字 - 当连接MQTT时使用MQTT PUB格式，否则使用MSGR格式
### 海康威视门铃
- **型号**：DS-KV6113-WPE1(C)，DS-KV8113-WPE1(C)，VillaVTO系列
- **功能**：摄像头快照，运动检测（VMD），门控，事件触发器，ISAPI健康状态
- **检测**：Docker容器`hikvision-doorbell`管理ISAPI连接
- **协议**：ISAPI HTTP摘要身份验证 + Docker Unix套接字API
- **要求**：Docker容器`hikvision-doorbell`，ISAPI凭证（`HIKVISION_DOORBELL_HOST/USER/PASSWORD`）
## 测试
该项目有4级测试层次结构（详见`AGENTS.md`）：
| 套件 | 测试 | 覆盖率 | 命令 |
|-------|-------|----------|---------|
| 单元测试 | 378 | **>80%** | `pytest tests/unit/ -v --tb=short` |
| 集成测试 | 25 | **66%** | `pytest tests/integration/ -q` |
| 烟雾测试 | 25 | HTTP验证 | `pytest tests/smoke/ -q` |
| 端到端测试 | 9 | HTTP验证 | `pytest tests/e2e/ -q` |
单元测试在CI中运行。集成测试，烟雾测试和端到端测试在缺少其依赖项（MQTT代理，正在运行的服务器）时跳过。
服务器遵循[MCP服务器标准](https://github.com/paulomac1000/ai-skills/blob/main/skills/mcp-server-architect/mcp-server-standards.md)，成熟度为L2/L3。
## Claude Desktop配置
将以下内容添加到您的`claude_desktop_config.json`：
```json
{
"mcpServers": {
"local-home-devices": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:9101/sse"]
}
}
}
```
## 许可证
MIT - 有关详细信息，请参见[LICENSE](LICENSE)。
