Home Assistant MCP

一个用于通过AI助手控制Home Assistant设备的模型上下文协议（MCP）集成。

概览

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

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

前提条件

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

安装

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

cd home-assistant
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -U pip
pip install uv
uv pip install -e .

配置

获取Home Assistant长期访问令牌

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

在Cursor AI中设置

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

{
  "mcpServers": {
    "home_assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/home-assistant-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "HOME_ASSISTANT_TOKEN": "your_home_assistant_token_here"
      },
      "inheritEnv": true
    }
  }
}

替换：

• /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设备时创造更加无缝的用户体验。