Home MCP Bridge

主页MCPBridge

通过模型上下文协议（MCP）为AI助手集成本地macOS HomeKit。

用自然语言控制整个智能家居 -没有Homebridge，没有家庭助理，没有云服务。只需直接访问HomeKit即可。

这是什么？

HomeMCPBridge是一款macOS应用程序，可让AI助手（Claude和其他支持MCP的人）直接控制您的HomeKit设备。让你的人工智能“关闭客厅的灯”或“将卧室设置为50%的亮度”，它就会工作。

特性

• 本地HomeKit -直接访问苹果的HomeKit框架，无需桥接或黑客攻击
• MCP协议 -适用于Claude Code、Claude Desktop和任何兼容MCP的AI
• 所有设备类型 -灯、开关、插座、风扇、锁、车库门、恒温器
• 完全控制 -开/关、亮度、颜色（色调/饱和度）、锁定/解锁、打开/关闭
• 菜单栏应用程序 -在后台安静运行，并显示状态窗口
• 插件系统 -使用Govee、加密NVR等进行扩展
• 设备链接 -将HomeKit设备与插件对应设备链接以避免重复
• MCPPost -向您的AI系统广播实时传感器事件
• 相机快照 -从HomeKit和Scrypted相机捕获图像
• 运动事件 -监控运动传感器、门铃和接触传感器

需求

• macOS 14.0（索诺玛）或更高版本
• 在Apple Home应用程序中配置的支持HomeKit的设备
• MCP兼容的人工智能助手（Claude Code、Claude Desktop等）

安装

选项1：下载版本

下载最新 .dmg 从 发布 页面。

选项2：从源代码构建

1. 克隆此仓库：

   git clone https://github.com/coalsi/HomeMCPBridge.git
   cd HomeMCPBridge

1. 在Xcode中打开：

   open HomeMCPBridge.xcodeproj

1. 在签名和能力中选择您的开发团队

1. 构建并运行（Cmd+R）-选择“我的Mac（Mac Catalyst）”

1. 出现提示时授予HomeKit访问权限

配置

将以下内容添加到MCP配置文件中：

克劳德代码 (.mcp.json 在您的项目或 ~/.claude/mcp.json):

{
  "mcpServers": {
    "homekit": {
      "command": "/Applications/HomeMCPBridge.app/Contents/MacOS/HomeMCPBridge",
      "args": []
    }
  }
}

适用于克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "homekit": {
      "command": "/Applications/HomeMCPBridge.app/Contents/MacOS/HomeMCPBridge",
      "args": []
    }
  }
}

用法

配置后，您可以问您的AI以下问题：

• “列出我的所有HomeKit设备”
• “打开厨房的灯”
• “将客厅灯设置为50%亮度”
• “车库里的温度是多少？”
• “把后院的灯都关掉”
• “锁上前门”
• “车库门开着吗？”
• “从前门摄像头拍摄快照”
• “后院有动静吗？”

可用的MCP工具

设备控制

相机

运动与活动

加密NVR（需要配置）

支持的设备类型

• 光 -开/关、亮度、颜色（色调/饱和度）
• 开关 -开/关
• 奥特莱斯 -开/关
• 粉丝 -开/关
• 锁 -锁定/解锁
• 车库门 -打开/关闭
• 恒温器 -读取温度（控制即将到来）
• 传感器 -读取值
• 相机 -捕获快照
• 运动传感器 -检测运动/占用情况
• 接触传感器 -门窗打开/关闭

______________________________________________________________________

应用程序标签

状态

智能家居设置概述：

• Apple HomeKit设备数量
• 插件状态和设备计数
• 设备链接计数
• 应用程序设置（菜单栏、dock图标）

设备

浏览按房间组织的所有设备：

• 点击（i）链接/取消链接设备
• 显示设备来源（HomeKit、Govee等）
• 表示链接的设备

插件

配置第三方集成：

• Govee-智能灯具和电器
• 加密NVR-网络摄像机

MCPPost

向您的AI广播实时传感器事件：

• 配置webhook端点URL
• 启用/禁用事件广播
• 查看最近的事件及其状态
• 测试端点连接

设置

完整的设置指南，包括：

• MCP配置片段
• 插件设置说明（Govee、Scrypted）
• MCPPost配置
• 设备链接指南

日志

调试的完整活动日志：

• 所有MCP工具调用
• 插件活动
• 事件通知
• 清除和滚动控件

______________________________________________________________________

设备链接

当你在HomeKit和插件（如Govee）中都有相同的设备时，你可以将它们链接起来，这样它们就被视为一个设备：

1. 去 设备 标签
2. 点击 （i） 任何设备上的按钮
3. 选择 “链接设备…”
4. 从其他来源选择相应的设备

链接的设备会自动使用功能最强大的源代码（插件通常比HomeKit具有更多功能）。

______________________________________________________________________

MCPPost（活动广播）

MCPPost将实时传感器事件广播到自定义HTTP端点，使您的AI系统（如Jarvis）能够接收推送通知。

配置

1. 开放式家庭MCPBridge
2. 去 MCPPost 标签
3. 输入您的端点URL（例如。， http://localhost:8000/api/events)
4. 通过切换启用广播
5. 点击“测试端点”进行验证

支持的活动

• 运动传感器 -检测到/清除运动
• 占用传感器 -房间入住率变化
• 门铃 -戒指事件
• 接触传感器 -门窗打开/关闭

事件负载

{
  "event_id": "uuid",
  "event_type": "motion|occupancy|doorbell|contact",
  "source": "HomeKit",
  "timestamp": "2024-01-18T21:00:00Z",
  "sensor": {
    "name": "Front Door Motion",
    "id": "sensor-uuid",
    "room": "Hallway",
    "home": "Home"
  },
  "data": {
    "detected": true,
    "state": "open",
    "isOpen": true
  }
}

______________________________________________________________________

插件系统

内置插件

政府设置

1. 在手机上打开Govee Home应用程序
2. 首选 设置>关于我们>申请API密钥
3. 等待批准（通常在几天内）
4. 从电子邮件中复制您的API密钥
5. 在HomeMCPBridge中，转到 插件>Govee 并输入您的API密钥
6. 启用Govee插件

加密NVR设置

1. 在您的网络上安装并配置Scrypted
2. 注意你的加密服务器URL（例如。， https://mac-mini.local:10443)
3. 安装 @scrypted/webhook Scrypted中的插件
4. 为每个摄像头创建一个摄像头webhook并记下令牌
5. 在HomeMCPBridge中，转到 插件>加密 并输入凭据
6. 使用 scrypted_set_webhook_token 配置每个相机令牌的工具

______________________________________________________________________

插件开发指南

想添加对另一个智能家居平台的支持吗？以下是如何创建自定义插件。

插件协议

protocol DevicePlugin: AnyObject {
    var identifier: String { get }
    var displayName: String { get }
    var isEnabled: Bool { get set }
    var isConfigured: Bool { get }
    var configurationFields: [PluginConfigField] { get }

    func initialize() async throws
    func shutdown() async
    func listDevices() async throws -> [UnifiedDevice]
    func getDeviceState(deviceId: String) async throws -> [String: Any]
    func controlDevice(deviceId: String, action: String, value: Any?) async throws -> ControlResult
    func configure(with credentials: [String: String]) async throws
    func clearCredentials()
}

注册您的插件

func application(_ application: UIApplication, didFinishLaunchingWithOptions...) {
    PluginManager.shared.register(MyPlatformPlugin())
}

______________________________________________________________________

隐私

主页MCPBridge：

• 完全在Mac上运行
• 通过Apple的框架直接与HomeKit设备通信
• 不向外部服务器发送任何数据（您配置的MCPPost除外）
• 本地设备控制不需要互联网连接

故障排除

“未找到设备”

• 确保您在Apple Home应用程序中设置了设备
• 在应用程序首次启动时授予HomeKit权限
• 尝试重新启动应用程序

“无法访问设备”

• 检查设备是否已通电并连接到您的网络
• 验证它在Apple Home应用程序中显示为可访问

MCP未连接

• 确保应用程序正在运行（检查菜单栏）
• 验证MCP配置中的路径是否与安装应用程序的位置匹配
• 更改配置后重新启动AI助手

加密快照不起作用

• 确保已安装@scrypted/webhook插件
• 为Scrypted中的每个摄像头创建摄像头webhook
• 使用 scrypted_set_webhook_token 配置令牌

贡献

欢迎投稿！请随时打开问题或提交PR。

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• 基于苹果的HomeKit框架构建
• 使用 模型上下文协议 通过Anthropic