项目2026-11-10 · 智涌AI

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

ha-mcp 头图:对比 Home Assistant 自带 MCP Server 与 ha-mcp 在实体范围、建自动化、改仪表盘上的差别,标注 87 个 MCP 工具、最新正式版 9.1.2、MIT 许可证

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 Serverha-mcp
控制设备、查状态只限暴露给 Assist 的实体全部实体
建 / 改自动化、脚本、场景不行可以
改仪表盘不行可以
读历史、日志、执行记录不行可以
备份、HACS、设备注册表不行可以

官方的建议是:只想语音控灯,用自带的就够;想让 AI 帮你搭和维护整套智能家居,再上 ha-mcp。

怎么用

推荐方式是装成集成,服务器直接跑在 Home Assistant 进程里,四种安装类型(OS、Supervised、Container、Core)都支持:

  1. Home Assistant 2026.8–2026.10:打开 HACS,搜 HA-MCP,点 Download。2026.11 及以上:设置 → Marketplace,搜 HA-MCP,点 Install。
  2. 重启 Home Assistant。
  3. 准备一个管理员身份。更稳妥的做法是在「设置 → 人员 → 添加人员」里新建账号,勾上允许登录、仅限本地访问、管理员。
  4. 设置 → 设备与服务 → 添加集成,选 HA-MCP Server,填账号或令牌,再选客户端的连接方式:经 Home Assistant 远程访问(先用 Secret URL 最简单)或局域网直连。两项默认都关。
  5. 到这个集成的「配置」页复制连接地址,贴进 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 这类本来就会按需加载工具的客户端,官方建议保持关闭。

核验记录

先给它一条只读连接,让它把现有自动化讲一遍,再决定要不要放开写权限。

适合谁,不适合谁

适合:已经在用 Home Assistant、自动化写了一堆但懒得手改 YAML 的人;想让 Claude 或 ChatGPT 帮忙排查「为什么这条自动化没触发」的人;家里设备多、仪表盘经常要调整的人。

不适合:只想语音开关灯的,用 Home Assistant 自带的 MCP Server 集成就行,权限面更小。门锁、燃气阀这类设备接进来要格外小心,管理员令牌一旦泄露,拿到的人能做的事和你一样多,可以在 ha-mcp 的设置面板里给这类工具单独加审批策略。还没装过 MCP 的话,可以先看站内的 MCP 是什么、怎么配置。

最后

家里有 Home Assistant 的话,先按上面第 3 步建一个专用管理员账号,装好集成后用只读地址连上 Claude,问一句「我家有哪些自动化,哪条最近没触发过」。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。