ha-mcp 是什么:让 AI 直接管 Home Assistant

ha-mcp 是一个开源 MCP 服务器,让 Claude、ChatGPT 等助手直接读写你的 Home Assistant:建自动化、改仪表盘、按运行记录排查故障。11 月 10 日我们对照官方 README、安装文档和 v9.1.2 发布页,把装法、权限和只读开关整理成这篇。
它是什么
ha-mcp 用 FastMCP 写成,把 Home Assistant 的实体、服务、自动化、仪表盘等能力包装成 MCP 工具。你在 AI 客户端里说「日落时打开门廊灯」,它会建一条带触发器和动作的自动化;说「这个人体感应自动化不灵了」,它去读执行记录(trace)找原因。
| 仓库 | github.com/homeassistant-ai/ha-mcp |
|---|---|
| 维护方 | homeassistant-ai 组织(社区项目,不是 Home Assistant 官方出品) |
| 许可证 | MIT |
| 热度 | GitHub 6,137 星(GitHub API,2026-11-10 14:05 北京时间);PyPI 包 ha-mcp 近 7 天下载 196,503 次(pypistats,截至 2026-11-10) |
| 运行要求 | Home Assistant 2026.8.0+(集成方式);PyPI 包要求 Python 3.13–3.14 |
| 最新正式版 | v9.1.2(发布于 2026-11-08 23:45,北京时间);master 每次推送另出 .dev 版 |
解决什么问题
Home Assistant 自己就带一个 MCP Server 集成,但它走 Assist 语音管线,只能控制你已经暴露给 Assist 的设备,适合「把客厅灯关了」这类指令。平时更费时间的是另一类活:写自动化的 YAML、调仪表盘卡片、翻日志查为什么半夜灯会亮。ha-mcp 主要补这一块。
| 能力 | 自带 MCP Server | ha-mcp |
|---|---|---|
| 控制设备、查状态 | 只限暴露给 Assist 的实体 | 全部实体 |
| 建 / 改自动化、脚本、场景 | 不行 | 可以 |
| 改仪表盘 | 不行 | 可以 |
| 读历史、日志、执行记录 | 不行 | 可以 |
| 备份、HACS、设备注册表 | 不行 | 可以 |
官方的建议是:只想语音控灯,用自带的就够;想让 AI 帮你搭和维护整套智能家居,再上 ha-mcp。
怎么用
推荐方式是装成集成,服务器直接跑在 Home Assistant 进程里,四种安装类型(OS、Supervised、Container、Core)都支持:
- Home Assistant 2026.8–2026.10:打开 HACS,搜 HA-MCP,点 Download。2026.11 及以上:设置 → Marketplace,搜 HA-MCP,点 Install。
- 重启 Home Assistant。
- 准备一个管理员身份。更稳妥的做法是在「设置 → 人员 → 添加人员」里新建账号,勾上允许登录、仅限本地访问、管理员。
- 设置 → 设备与服务 → 添加集成,选 HA-MCP Server,填账号或令牌,再选客户端的连接方式:经 Home Assistant 远程访问(先用 Secret URL 最简单)或局域网直连。两项默认都关。
- 到这个集成的「配置」页复制连接地址,贴进 AI 客户端。
连接地址有两种形式:
https://<你的 HA 域名>/api/webhook/<webhook-id>
http://<HA 的 IP>:9584/private_<随机串>
Container、Core 用户也可以在别的机器上跑 Docker 镜像 ghcr.io/homeassistant-ai/ha-mcp,或者用 uvx ha-mcp@latest 起一个 HTTP 服务。各家客户端(Claude Code、Gemini CLI、Cursor、Open WebUI 等 15 种以上)的配置,官方做了一个 Setup Wizard 网页直接生成。
两个常用开关:
# 小模型、本地模型:别一次塞 87 个工具,改成按需搜索
ENABLE_TOOL_SEARCH=true
# 给自动运行的 Agent 一条只读连接
https://example.com/private_your_secret/readonly
打开工具搜索后,工具列表只剩 ha_search_tools 和读、写、删三个代理工具,再加几个常驻工具。客户端可以据此设规则:读自动放行,写要确认,删要二次确认。Claude Desktop、Claude Code 这类本来就会按需加载工具的客户端,官方建议保持关闭。
核验记录
- 版本:GitHub Releases 最新正式版 v9.1.2,修了 HACS 里同一个集成出现两个商店条目的问题;PyPI 上的 ha-mcp 也是 9.1.2。
- 工具数:README 自动生成的工具表列出 87 个,其中读写文件、改 YAML 的几个标着 beta,默认不开,要额外加一个 File & YAML Tools 条目才能用。
- 隐私:README 写明目前没有遥测,计划中的匿名统计会跟随 Home Assistant 自己的分析设置,上线前至少提前一个月公告;提交 bug 报告要你点头。
- 只读:
/readonly是连接模式,不是另一套凭证。同一个地址去掉后缀照样能写,所以别把可写地址也交给同一个 Agent。 - 安装方式只能选一种。集成、Add-on、Docker、stdio 同时挂在一个客户端里,官方说这是连接卡住的常见原因。
先给它一条只读连接,让它把现有自动化讲一遍,再决定要不要放开写权限。
适合谁,不适合谁
适合:已经在用 Home Assistant、自动化写了一堆但懒得手改 YAML 的人;想让 Claude 或 ChatGPT 帮忙排查「为什么这条自动化没触发」的人;家里设备多、仪表盘经常要调整的人。
不适合:只想语音开关灯的,用 Home Assistant 自带的 MCP Server 集成就行,权限面更小。门锁、燃气阀这类设备接进来要格外小心,管理员令牌一旦泄露,拿到的人能做的事和你一样多,可以在 ha-mcp 的设置面板里给这类工具单独加审批策略。还没装过 MCP 的话,可以先看站内的 MCP 是什么、怎么配置。
最后
家里有 Home Assistant 的话,先按上面第 3 步建一个专用管理员账号,装好集成后用只读地址连上 Claude,问一句「我家有哪些自动化,哪条最近没触发过」。