JinDaGe - home-assistant-integration MCP Details

article

README

🚀 家庭助手 MCP

家庭助手 MCP 是一个模型上下文协议（MCP）集成，借助人工智能助手实现对家庭助手设备的控制，为智能家居控制带来便捷体验。

🚀 快速开始

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

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

📦 安装指南

先决条件

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

安装步骤

克隆此仓库。
设置 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 .

📚 详细文档

配置

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

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

在 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 现在支持高级灯光控制功能：

颜色控制：设置兼容灯的任意 RGB 颜色。
- 使用 RGB 值（每个组件 0 - 255）指定颜色。
- 示例：set_device_color("light.living_room", 255, 0, 0) 设置为红色。
亮度控制：调整灯光亮度。
- 可选的亮度参数（0 - 255）。
- 可与颜色更改结合使用。
- 示例：set_device_color("light.dining_room", 0, 0, 255, brightness=128) 设置为中等亮度蓝色。

故障排除

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

未来功能

动态实体暴露

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

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

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

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

home-assistant-integration