Home Assistant MCP 服务器

一个用于集成 Home Assistant 的模型上下协议 (MCP) 服务器，允许你通过 AI 助手控制智能家居设备。

功能特性

• 实体管理: 获取所有实体或特定实体的状态
• 设备控制: 开关、切换灯光、开关等设备
• 灯光控制: 设置灯光亮度和 RGB 颜色
• 空调控制: 设置温控器温度和 HVAC 模式
• 服务调用: 使用自定义参数调用任何 Home Assistant 服务
• 历史记录: 获取实体的历史状态变化
• 注册表访问: 查询区域、设备和实体注册表
• 模板渲染: 渲染 Home Assistant 模板

安装

方式一：直接使用 npx（推荐）

无需下载代码，直接使用 npx 运行：

npx home-assistant-mcp-server-n

方式二：从源码安装

cd HomeAssistantMcp
npm install
npm start

方式三：全局安装

npm install -g home-assistant-mcp-server-n
home-assistant-mcp-server-n

配置

在 Home Assistant 中创建长期访问令牌：

1. 进入你的 Home Assistant 实例
2. 点击你的用户资料（左下角）
3. 滚动到"长期访问令牌"
4. 点击"创建令牌"
5. 给它一个名称（例如 "MCP Server"）并复制令牌

设置以下环境变量：

export HOMEASSISTANT_URL="http://localhost:8123"  # 你的 Home Assistant URL
export HOMEASSISTANT_TOKEN="your_long_lived_access_token"

使用方法

Claude Desktop 配置

添加到你的 Claude Desktop 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

使用 npx 方式（推荐）

{
  "mcpServers": {
    "home-assistant": {
      "command": "npx",
      "args": ["home-assistant-mcp-server-n"],
      "env": {
        "HOMEASSISTANT_URL": "http://localhost:8123",
        "HOMEASSISTANT_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}

使用本地路径方式

{
  "mcpServers": {
    "home-assistant": {
      "command": "node",
      "args": ["/path/to/HomeAssistantMcp/src/index.js"],
      "env": {
        "HOMEASSISTANT_URL": "http://localhost:8123",
        "HOMEASSISTANT_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}

可用工具

基本实体操作

• homeassistant_get_states - 获取所有状态，支持可选过滤
• homeassistant_get_state - 获取特定实体的状态

设备控制

• homeassistant_turn_on - 打开设备
• homeassistant_turn_off - 关闭设备
• homeassistant_toggle - 切换设备状态

灯光控制

• homeassistant_set_brightness - 设置灯光亮度 (0-255)
• homeassistant_set_color - 设置 RGB 颜色 [r, g, b]

空调控制

• homeassistant_set_temperature - 设置目标温度
• homeassistant_set_hvac_mode - 设置 HVAC 模式 (制热/制冷/自动/关闭)

高级功能

• homeassistant_call_service - 调用任何 Home Assistant 服务
• homeassistant_get_services - 列出所有可用服务
• homeassistant_get_history - 获取历史状态变化
• homeassistant_get_config - 获取 Home Assistant 配置
• homeassistant_get_areas - 列出所有区域
• homeassistant_get_devices - 列出所有设备
• homeassistant_get_entities - 列出所有实体
• homeassistant_render_template - 渲染模板

使用示例

打开灯光

使用 homeassistant_turn_on，entity_id 为 "light.living_room"

设置灯光亮度为 50%

使用 homeassistant_set_brightness，entity_id 为 "light.bedroom"，brightness 为 127

设置灯光颜色为红色

使用 homeassistant_set_color，entity_id 为 "light.kitchen"，rgb_color 为 [255, 0, 0]

设置温控器为 22°C

使用 homeassistant_set_temperature，entity_id 为 "climate.thermostat"，temperature 为 22

获取所有灯光状态

使用 homeassistant_get_states，filter 为 "light."

渲染模板

使用 homeassistant_render_template，template 为 "{{ states('sensor.temperature') }}"

测试

npm test

API 参考

Home Assistant REST API

此服务器使用 Home Assistant REST API。更多信息请参阅： https://developers.home-assistant.io/docs/api/rest/

许可证

MIT