家庭助手MCP

Name: 家庭助手MCP
Author: hpohlmann

作者：hpohlmann22 星标更新：2025-11-03

安装使用来源：spider==github.com

项目介绍

Home Assistant MCP

这是一个用于通过AI助手控制Home Assistant设备的Model Context Protocol (MCP)集成。

概述

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

在您的Home Assistant实例中搜索实体
控制设备（打开或关闭）
控制灯光颜色和亮度

预备条件

Python 3.11 或更高版本
运行中的Home Assistant实例，并可通过API访问
Home Assistant长效访问令牌

安装

通过Smithery安装

要通过Smithery自动安装Claude Desktop的Home Assistant集成：

npx -y @smithery/cli install @hpohlmann/home-assistant-mcp --client claude

手动安装

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

配置

获取Home Assistant长效访问令牌

转到您的Home Assistant实例
导航到您的个人资料（点击侧边栏中的用户名）
向下滚动到“长效访问令牌”
创建一个具有描述性名称的新令牌，如“MCP集成”
复制该令牌（您只能看到一次）

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

颜色控制：为兼容灯光设置任意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) 设为中等亮度蓝色

故障排除

如果遇到身份验证错误，请检查您的令牌是否正确且未过期
检查您的Home Assistant实例是否可以在配置的URL上访问
对于颜色控制问题：
- 验证您的灯光实体是否支持RGB颜色控制
- 在尝试更改颜色之前，确保灯光已开启

未来能力

动态实体暴露

当前实现需要两步过程来控制设备：

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

计划增强功能是创建一种更动态的方式来向控制设备工具暴露实体，使AI能够：

通过更自然的命令直接控制设备（例如，“关闭厨房灯”）
缓存频繁使用的实体以加快访问速度
支持更复杂的操作，如调整亮度、温度或其他属性
更直观地处理实体组和场景