AI导哈

智能家居控制协议

Home Assistant MCP是一个通过AI助手控制Home Assistant设备的模型上下文协议集成，支持设备搜索、开关控制及灯光颜色亮度调节。

  • by hpohlmann
  • Python
  • 本地部署
  • 24 星标
  • 更新于
在 GitHub 查看 hpohlmann/home-assistant-mcp

使用说明

家庭助理MCP

用于使用AI助手控制家庭助理设备的模型上下文协议（MCP）集成。

概述

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

  1. 在Home Assistant实例中搜索实体
  2. 控制设备（打开/关闭）
  3. 控制灯光颜色和亮度

先决条件

  • Python 3.11或更高版本
  • Home Assistant实例正在运行并可通过API访问
  • 家庭助理长期访问令牌

安装

通过Smithery安装

通过以下方式自动安装Claude Desktop的家庭助理集成 史密瑟里:

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

手动安装

  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 .

配置

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

  1. 转到您的家庭助理实例
  2. 导航到您的个人资料（单击侧栏中的用户名）
  3. 向下滚动到“长期访问令牌”
  4. 创建一个具有描述性名称的新令牌，如“MCP Integration”
  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 使用您的家庭助理长期访问令牌

家庭助理URL配置

默认情况下，MCP尝试在以下位置连接到家庭助理 http://homeassistant.local:8123.

如果您的家庭助理位于其他URL，您可以修改 HA_URL 变量in app/config.py.

用法

配置后，您可以使用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