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 集成”
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 设备时创建更无缝的用户体验。