Home Assistant MCP

家庭助理 MCP

使用 AI 助手控制家庭助手设备的模型上下文协议 (MCP) 集成。

概述

此 MCP 允许 AI 助手控制您的 Home Assistant 设备。它提供以下工具：

1. 在您的 Home Assistant 实例中搜索实体
2. 控制设备（打开/关闭）
3. 控制灯光颜色和亮度

先决条件

• Python 3.11 或更高版本
• Home Assistant 实例正在运行并可通过 API 访问
• Home Assistant 长期访问令牌

安装

1. 克隆此存储库
2. 设置 Python 环境：

配置

获取 Home Assistant 长期访问令牌

1. 转到您的 Home Assistant 实例
2. 导航到您的个人资料（单击侧栏中的用户名）
3. 向下滚动到“长寿命访问令牌”
4. 创建一个具有描述性名称的新令牌，例如“MCP Integration”
5. 复制令牌（您只会看到一次）

在 Cursor AI 中设置

将以下配置添加到 Cursor 中的 MCP 配置中：

代替：

• /path/to/your/home-assistant替换为该目录的实际路径
• your_home_assistant_token_here与您的 Home Assistant 长期访问令牌

Home Assistant URL 配置

默认情况下，MCP 尝试通过http://homeassistant.local:8123连接到 Home Assistant。

如果您的 Home Assistant 位于不同的 URL，您可以修改app/config.py中的HA_URL变量。

用法

配置完成后，您可以使用 Cursor AI 来控制您的 Home Assistant 设备：

• 搜索设备：“查找我的客厅灯”
• 控制设备：“打开厨房灯”
• 控制灯光颜色：“将我的客厅灯设置为红色”
• 调整亮度：“将餐厅灯光设置为蓝色，亮度为 50%”

灯光控制功能

MCP 现在支持高级灯光控制功能：

1. 颜色控制：为兼容灯设置任意 RGB 颜色
   • 使用 RGB 值指定颜色（每个成分为 0-255）
   • 例如： set_device_color("light.living_room", 255, 0, 0)表示红色
2. 亮度控制：调节灯光亮度
   • 可选亮度参数（0-255）
   • 可以与颜色变化结合
   • 例如： set_device_color("light.dining_room", 0, 0, 255, brightness=128)表示中等亮度的蓝色

故障排除

• 如果出现身份验证错误，请验证您的令牌是否正确且未过期
• 检查您的 Home Assistant 实例是否可以通过配置的 URL 访问
• 对于颜色控制问题：
  • 验证您的灯光实体是否支持 RGB 颜色控制
  • 尝试改变颜色之前，请检查灯是否已打开

未来能力

动态实体暴露

当前实施需要两步过程来控制设备：

1. 使用自然语言搜索实体
2. 使用其特定的entity_id控制实体

计划中的增强功能是创建一种更加动态的方式将实体暴露给控制设备工具，从而使 AI 能够：

• 通过更自然的命令直接控制设备（例如“关闭厨房灯”）
• 缓存常用实体以便更快地访问
• 支持更复杂的操作，如调整亮度、温度或其他属性
• 更直观地处理实体组和场景

这将大大减少操作时间，并在通过 AI 助手控制 Home Assistant 设备时创造更加无缝的用户体验。