🚀 家庭助手 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，以便直接控制它们。 例如：
- 对于灯：“客厅灯”。
- 对于智能插座：“厨房插座”。
这将允许 MCP 直接与设备交互，而无需先搜索其 ID。