AI导哈

智能家居控制服务

一个基于模型上下文协议（MCP）的服务，实现Claude与Homebridge的无缝集成，通过自然语言控制HomeKit配件。

  • by EliabLemus
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 EliabLemus/homebridge-mcp-server

使用说明

Homebridge MCP服务器

一个模型上下文协议（MCP）服务器，在Claude和Homebridge之间提供无缝集成，实现了对HomeKit配件的人工智能控制。

什么是MCP？

模型上下文协议（MCP）是一个开放标准，使AI助手能够安全地连接到外部数据源和工具。此服务器实现了MCP，将Claude与您的Homebridge设置连接起来，允许您对智能家居设备进行自然语言控制。

特性

  • 列出并发现 Homebridge管理的所有HomeKit配件
  • 控制单个设备 （电源开/关、亮度、色调、饱和度）
  • 快速切换 即时设备状态更改功能
  • 设备详细检查 具有特性和能力
  • 房间布局管理 和组织
  • 批量控制 使用名称模式的多个设备
  • 缓存附件重置 刷新设备信息

先决条件

  • 安装并运行Config UI X的Homebridge
  • Homebridge必须正在运行 不安全模式 (-I 标志）以启用附件控制
  • Docker（用于容器化部署）或Python 3.7+
  • 对Homebridge实例的网络访问

安装

选项1:Docker（推荐）

# Clone the repository
git clone https://github.com/EliabLemus/homebridge-mcp-server.git
cd homebridge-mcp-server

# Build the Docker image
docker build -t homebridge-mcp-server .

# Run the container
docker run -it --rm \
  -e HOMEBRIDGE_HOST=homebridge.local:8081 \
  homebridge-mcp-server

选项2:Python安装

# Clone the repository
git clone https://github.com/EliabLemus/homebridge-mcp-server.git
cd homebridge-mcp-server

# Install dependencies
pip install -r requirements.txt

# Run the server
python homebridge_server.py

配置

设置 HOMEBRIDGE_HOST 指向Homebridge Config UI X实例的环境变量：

export HOMEBRIDGE_HOST=homebridge.local:8081
# or for custom IP/port
export HOMEBRIDGE_HOST=192.168.1.100:8581

启用Homebridge不安全模式

为了控制配件，Homebridge必须在不安全模式下运行。添加 -I 标记到Homebridge启动命令：

# If using systemd
sudo systemctl edit homebridge
# Add: ExecStart=/usr/local/bin/homebridge -I

# If using PM2
pm2 delete homebridge
pm2 start homebridge -- -I

# If using Docker
docker run -it --rm homebridge/homebridge -I

安全说明：不安全模式允许API访问以控制您的配件。确保您的Homebridge实例未暴露在互联网上。

可用工具

核心功能

  • list_accessories() -显示所有可用的HomeKit配件
  • get_accessories_layout() -基于展厅的组织
  • get_accessory_details(unique_id) -获取详细的设备信息

设备控制

  • quick_toggle(unique_id) -切换设备电源状态
  • control_accessory(unique_id, action, value) -精确的设备控制
    • 行动： power, brightness, hue, saturation
    • 价值观： on/off, 0-100 （亮度/饱和度）， 0-360 （色调）

管理的职能

  • reset_cached_accessories() -清除并刷新设备缓存
  • create_room_groups() -按房间自动组织设备
  • control_room_devices(pattern, action, value) -按名称模式控制多个设备

使用示例

使用克劳德桌面

通过添加到您的配置中，配置Claude Desktop以使用此MCP服务器：

{
  "mcp": {
    "servers": {
      "homebridge": {
        "command": "docker",
        "args": ["run", "-i", "--rm", "-e", "HOMEBRIDGE_HOST=homebridge.local:8081", "homebridge-mcp-server"]
      }
    }
  }
}

然后你可以和克劳德互动：

"Show me all my smart home devices"
"Turn on the living room lights"
"Set bedroom lamp brightness to 50%"
"Turn off all Christmas decorations"

命令行用法

# List all accessories
echo '{"method": "tools/call", "params": {"name": "list_accessories"}}' | python homebridge_server.py

# Control a specific device
echo '{"method": "tools/call", "params": {"name": "control_accessory", "arguments": {"unique_id": "abc123", "action": "power", "value": "on"}}}' | python homebridge_server.py

api参考

认证

服务器使用Homebridge的 /api/auth/noauth 用于身份验证的端点。令牌是自动管理和缓存的。

错误处理

常见错误场景和解决方案：

  • HTTP 400“characteristicType不应为null”：检查设备兼容性和Homebridge不安全模式
  • HTTP 404：使用验证设备unique_id是否存在 list_accessories()
  • 连接被拒绝：确认Homebridge配置UI X正在运行并可访问

故障排除

设备没有响应

  1. 验证Homebridge是否处于不安全模式(-I 旗帜）
  2. 检查与Homebridge实例的网络连接
  3. 重置缓存的附件： reset_cached_accessories()

过时的设备信息

  • 使用 reset_cached_accessories() 刷新设备缓存
  • 配置更改后重新启动Homebridge网桥

权限问题

  • 确保MCP服务器可以访问您的Homebridge实例
  • 如果在不同网络上运行，请检查防火墙设置

发展

项目结构

├── Dockerfile              # Container configuration
├── homebridge_server.py    # Main MCP server implementation
├── requirements.txt        # Python dependencies
├── CLAUDE.md              # Claude-specific documentation
└── README.md              # This file

贡献

  1. 复刻仓库
  2. 创建要素分支
  3. 进行更改
  4. 使用Homebridge设置进行测试
  5. 提交拉取请求

测试

使用各种Homebridge设置测试服务器：

# Test connection
python homebridge_server.py --test-connection

# Validate device discovery
python homebridge_server.py --validate-devices

安全考虑

  • 网络安全：仅在受信任的网络上运行不安全模式
  • 访问控制：考虑防火墙规则以限制MCP服务器访问
  • 认证：服务器使用Homebridge的身份验证系统

许可证

MIT许可证-有关详细信息，请参阅许可证文件

相关项目

支持

对于问题和疑问：

相关 MCP