homeassistant-ai/ha-mcp · 上手攻略

仓库：homeassistant-ai/ha-mcp
链接：https://github.com/homeassistant-ai/ha-mcp
分类：skill
作者：Jay
更新：2026-07-12

这是什么

ha-mcp 是 Home Assistant 的非官方 MCP（Model Context Protocol）服务器，让 AI 助手（如 Claude、ChatGPT）能够直接与 Home Assistant 智能家居平台交互，从而用自然语言控制灯光、空调、传感器、自动化规则等所有家居设备。截至 2026 年 7 月 Stars 超过 3900，是增长最快的 Home Assistant AI 集成之一。

解决什么问题

自然语言控制家居：不用打开 App，直接对 AI 说"把客厅灯调暗一半并打开空调"
跨设备联动查询：一句话问"家里哪些灯开着？""今天用电量多少？"
AI 驱动自动化：让 AI 根据上下文自动创建或修改 Home Assistant 自动化规则
远程访问：通过 Nabu Casa 或 Webhook Proxy，无公网 IP 也能远程控制

快速安装

ha-mcp 支持多种安装方式，推荐按你的 Home Assistant 类型选择：

方式一：HACS 安装（最简单，推荐）

适用：Home Assistant OS / Supervised / Container / Core 均可

在 HACS 中添加自定义仓库：进入 HACS → Integrations → ⋮ → Custom repositories，添加： https://github.com/homeassistant-ai/ha-mcp-integration 类别选择 Integration
下载完成后重启 Home Assistant
进入 Settings → Devices & Services → Add Integration，搜索 HA-MCP Custom Component，选择 HA-MCP Server 并提交
在配置页面复制 Connect URL（也会打印在 Home Assistant 日志中）
将 Connect URL 粘贴到你的 AI 客户端，完成连接

方式二：Home Assistant Add-on（Home Assistant OS / Supervised）

添加仓库：在 App Store（2026.2 后改名为 Apps）中添加： https://github.com/homeassistant-ai/ha-mcp （若自动添加按钮不生效，手动在 ⋮ → Repositories 中粘贴）
在 App Store 中搜索并安装 Home Assistant MCP Server
启动后，在 Logs 标签页找到 MCP URL
将该 URL 填入 AI 客户端

方式三：Docker（Container / Core 用户）

# 使用 Setup Wizard 生成你的配置：https://homeassistant-ai.github.io/ha-mcp/setup/
# 或直接运行（需替换 YOUR_HA_URL 和 YOUR_TOKEN）

docker run -d \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_long_lived_access_token \
  -p 9584:9584 \
  ghcr.io/homeassistant-ai/ha-mcp:latest

方式四：PyPI / uvx

# 需要先有 Home Assistant 长期访问令牌
# 在 Home Assistant: 个人资料 → 长期访问令牌 → 创建令牌

uvx ha-mcp@latest \
  --homeassistant-url http://your-ha:8123 \
  --homeassistant-token YOUR_TOKEN

⚠️ 注意：不同安装方式对应不同的连接 URL，配置前请确认只使用一种安装方式，同时运行两种会导致客户端连接挂起。

核心用法

Claude Desktop 连接配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "Home Assistant": {
      "url": "http://localhost:9584/private_xxxxx"
    }
  }
}

💡 本地网络之外的客户端使用 Webhook URL（格式如 https://your-domain/ui.nabu.casa/api/webhook/xxxxx），需要 Nabu Casa 订阅或 Webhook Proxy 配置。

常用 MCP 工具（示例对话）

连接成功后，可直接用自然语言与 Home Assistant 交互：

用户："把所有灯关掉"
→ AI 调用 ha_turn_on / ha_turn_off 工具

用户："客厅现在温度是多少？"
→ AI 查询 ha_climate_get_temperature

用户："创建一个自动化：晚上10点自动关灯"
→ AI 调用 ha_create_automation 或 ha_script

用户："今天的能耗数据怎么样？"
→ AI 查询 ha_energy_stats 或对应集成数据

获取 Home Assistant 长期访问令牌

登录 Home Assistant Web UI
点击右上角头像 → Profile
滚动到 Long-Lived Access Tokens
点击 Create Token，输入名称（如 ha-mcp）
复制生成的令牌（只显示一次）

远程访问配置（无公网 IP 场景）

方案 A：Nabu Casa（官方云订阅）

已订阅 Nabu Casa 的用户，Webhook URL 格式为： https://your-ha.ui.nabu.casa/api/webhook/mcp_xxxxxxxx
在 HA-MCP 配置页面直接启用"Remote access via webhook"即可

方案 B：Webhook Proxy Add-on（已有反向代理）

同时安装 MCP Server Add-on + Webhook Proxy Add-on
启动后从 Proxy 日志复制远程 URL

方案 C：OpenAI Tunnel（绕过防火墙，Claude / ChatGPT 用户）

适合内网环境，通过 OpenAI Tunnel 建立出站连接
参考社区方案 norpol/hass-codex-tunnel-mcp

典型适用场景

场景	用法示例
语音控制全屋	"出门了，关闭所有灯并设防"
能耗管理	"分析过去一周的用电高峰"
自动化创建	"当我回家且天黑时，自动开客厅灯"
安防查询	"列出今天所有运动传感器触发的记录"
设备状态总览	"家里有哪些设备在线？哪些离线？"
远程维护	在外旅游时通过手机 Claude 查询家里状态

坑与注意

⚠️ stdio 传输问题：本地 stdio 模式存在已知连接问题（#1713），建议生产环境使用 HTTP 模式（Custom Component 或 Add-on）
⚠️ 多安装方式冲突：同一时间只配置一种安装方式，同时运行两个 ha-mcp 实例会导致客户端连接挂起
安全风险：MCP URL 包含密钥，勿在公开场合分享；建议开启 ha_auth（Home Assistant 账号认证）作为额外保护
版本兼容性：建议使用 Home Assistant 2026.2 及以上（某些功能如 App/Add-on 改名在旧版不存在）
文件编辑工具默认关闭：ha-mcp 的文件编辑功能（如修改 YAML）默认关闭，需单独添加 HA MCP Tools 集成条目才可使用
本地直连端口：同一网络内客户端可直接连接 http://<ha-ip>:9584/private_<random>，但该直连不加密，仅限可信局域网使用

与同类对比

方案	类型	协议	AI 客户端支持	配置难度
ha-mcp（本文）	MCP Server	MCP	Claude Desktop / ChatGPT / Cursor 等所有 MCP 客户端	⭐⭐ 简单
Home Assistant Alexa 集成	语音助手	Alexa	Amazon Echo	⭐⭐ 简单
Home Assistant Google Assistant	语音助手	Google Assistant	Google Home	⭐⭐ 简单
MQTT + AI 脚本	自定义方案	MQTT	需自建	⭐⭐⭐⭐ 复杂
n8n + Home Assistant	自动化工作流	Webhook/MQTT	不直接支持 AI 对话	⭐⭐⭐ 中等

一句话推荐结论

ha-mcp 是 Home Assistant 用户将 AI 助手引入智能家居的最佳入口，通过标准 MCP 协议让任何支持 MCP 的 AI 都能操控家中设备，安装简单（HACS 一键）、功能完整，是让 AI 真正"住进"你家的实用方案。