家庭助手 MCP

一个用于通过人工智能助手控制家庭助手设备的模型上下文协议（MCP）集成。

概述

此MCP允许人工智能助手控制您的家庭助手设备。它提供了以下工具：

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

先决条件

• Python 3.11或更高版本
• 运行中的家庭助手实例，可通过API访问
• 家庭助手长期访问令牌

安装

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

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

配置

获取家庭助手长期访问令牌

1. 转到您的家庭助手实例
2. 导航到您的配置文件（点击侧边栏中的用户名）
3. 滚动到底部“长期访问令牌”
4. 创建一个带有描述性名称的新令牌，例如“MCP 集成”
5. 复制令牌（您只会在创建时看到它）

在 Cursor AI 中设置

将以下配置添加到您的 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 您的长期家庭助手访问令牌

家庭助手 URL 配置

默认情况下，MCP 尝试连接到位于 http://homeassistant.local:8123 的家庭助手。

如果您的家庭助手位于不同的 URL，可以在 app/config.py 中修改 HA_URL 变量。

使用方法

配置完成后，您可以使用 Cursor AI 控制您的家庭助手设备：

• 搜索设备：例如，“查找我的客厅灯”
• 控制设备：例如，“打开厨房灯”
• 控制灯光颜色：例如，“将我的客厅灯设置为红色”
• 调整亮度：例如，“将我的餐厅灯设置为蓝色，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) 设置为中等亮度蓝色

故障排除

• 如果您遇到身份验证错误，请检查令牌是否正确且未过期
• 确保您的家庭助手实例可以访问配置的 URL
• 对于颜色控制问题：
  • 验证灯实体是否支持 RGB 颜色控制
  • 检查灯是否已打开，然后再尝试更改颜色

未来功能

动态实体暴露

当前实现需要通过自然语言搜索实体然后控制设备的两步过程：

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

计划中的增强是创建一种更动态的方式将实体暴露给 MCP，以便直接控制它们。

例如：

• 对于灯：“客厅灯”
• 对于智能插座：“厨房插座”

这将允许 MCP 直接与设备交互，而无需先搜索其 ID。