ha-mcp：用 AI 直接控制 Home Assistant

ha-mcp 是用 Python 写的 MCP 服务器，把 Home Assistant 的设备控制、状态查询与自动化管理变成 AI 助手可直接调用的 87 个工具。

Home Assistant 把家里的灯、传感器、门锁接进一套跑在本地的小系统，日常操作靠网页和手机 App 点。想让 Claude、ChatGPT 这类客户端直接读状态、改自动化，中间得放一个 MCP 服务器，把 HA 的接口翻译成模型能调用的工具。ha-mcp 干的就是这层活，README 里的自我定位是「非官方但好用」（The Unofficial and Awesome Home Assistant MCP Server）。仓库地址是 https://github.com/homeassistant-ai/ha-mcp，采用 MIT 许可证，主要语言是 Python，占 96.6%，目前 4895 个 star、224 个 fork、17 个开放 Issue，仓库创建于 2025-09-14。

安装路线有好几条：HACS 自定义集成（服务器跑在 Home Assistant 进程里）、Home Assistant app（旧称 add-on）、Docker 镜像、PyPI/uvx，以及本地 stdio。README 反复强调一个客户端只能配一种，同时挂两个会连接挂起。

主要功能

README 的徽章标着 tools-87，这个数字就是服务器对外暴露的工具总量。工具覆盖的范围从读设备状态一路延伸到改自动化、改仪表盘。

设备与实体读取。ha_get_device 和 ha_search 用来按设备或关键词读取实体状态与属性。这类数据量大的调用在客户端侧出过约 4 分钟超时的问题，后来修掉了。

仪表盘管理。ha_config_set_dashboard 让 AI 创建或修改 Lovelace 仪表盘。这个工具曾经持续超时，Issue 里讨论很多，现在状态是已解决。

自动化与 helper。创建和编辑自动化、helper 属于写入类调用，也在工具集覆盖范围内。写入操作在 add-on 加 mcp-proxy 的组合下出现过间歇超时。

家庭拓扑读取。ha_get_home_topology 是一次只读调用，把楼层与区域的层级结构合并返回，省掉多次读取注册表。

文件与 YAML 编辑。这项是可选的，默认关闭。要启用得在集成里额外添加第二个 entry 类型「HA-MCP File & YAML Tools」，它对 in-process、app、Docker、stdio 都有效。ha_config_set_yaml 在 v7.3.0 被移到 beta。

侧边栏管理面板。服务器运行时，Home Assistant 侧边栏会多出一个仅管理员可见的 HA-MCP 面板，用来管理 tools、feature flags、备份和主题。

认证方式。Webhook authentication 设成 ha_auth 时，远程客户端需要用 Home Assistant 账号登录，不再把秘密 URL 当凭证。OIDC 模式把远程访问交给 Authentik、Keycloak、Auth0 这类外部身份提供方。

安装与依赖

主体是 Python 项目，包配置在 pyproject.toml，仓库里还带了 Astro、JavaScript、CSS 写的站点与文档代码。仓库体积 46609 KB，默认分支 master。

README 推荐的首选方式是 HACS 自定义集成。它跑在 HA 进程内，Home Assistant OS、Supervised、Container、Core 四种安装类型都能用，而且不需要管理访问令牌。

其他方式各有前提。HA app 只适用于 Home Assistant OS 和 Supervised 两种安装；Docker 镜像地址是 ghcr.io/homeassistant-ai/ha-mcp；PyPI 包可以用 uvx ha-mcp@latest 拉起；本地 stdio 被 README 自己标注为不推荐。Container 和 Core 装不了 app，只能走 Docker、PyPI 或 stdio 这几条外部路线。

最短能跑通的用法

走 HACS 的完整流程只有五步。

1. 在 HACS 里打开 Integrations → ⋮ → Custom repositories，添加 https://github.com/homeassistant-ai/ha-mcp-integration，类别选 Integration，然后下载。
2. 重启 Home Assistant。
3. 进入 Settings → Devices & Services → Add Integration，搜 HA-MCP Custom Component，选 HA-MCP Server，点 Submit。创建这个条目就会启动服务器。
4. 在条目的 Configure 屏（Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure）复制连接 URL，Home Assistant 日志里也会打印一份，同时会有一条通知指路。
5. 把这个 URL 粘进 AI 客户端。

不用 HACS 的话，把仓库里的 custom_components/ha_mcp_tools/ 复制到 Home Assistant 的 config/custom_components/ 目录，重启，再按上面的步骤添加集成。

只在本机用，就在条目选项里关掉 Remote access via webhook，这样不会注册 webhook，直连端口和侧边栏面板照常工作。

关键参数

• 连接 URL 形态。远程走 https://<your-ha-domain>/api/webhook/<webhook-id>，经 Nabu Casa 或任何已经指向 Home Assistant 的反向代理；局域网内是 http://<ha-host>:8123/api/webhook/<webhook-id>；同一网络的客户端还能直连 http://<ha-ip>:9584/private_<random>。
• Remote access via webhook。关闭后完全不注册 webhook，服务器只在本机可达。
• Webhook authentication。设成 ha_auth 后，访问需要 Home Assistant 账号登录。
• HOMEASSISTANT_URL 与 HOMEASSISTANT_TOKEN。Docker、PyPI、stdio 这几条外部路线要指向 HA 地址并带上长期令牌。README 建议用管理员令牌，非管理员令牌能用但有功能限制。
• OIDC 认证。用外部身份提供方给远程访问加一道门槛，替代秘密 URL 的凭证作用。
• feature flags。文件与 YAML 编辑工具属于 opt-in，默认关闭，需要手动打开。

远程访问打开之后，连接 URL 本身就是凭证，把这串地址给谁，等于把 Home Assistant 的控制入口给谁。README 的说法是「把秘密 URL 当凭证」，收到 URL 的一方不需要再单独登录。

结果在哪里看

客户端连上以后，AI 的每一次调用都作用在 Home Assistant 实例上，结果直接反映到设备状态、自动化规则和仪表盘里，没有额外的输出文件。

服务器自己的信息分布在几个位置。连接 URL 出现在条目的 Configure 屏和 Home Assistant 日志中，启动确认走 HA 通知。运行时的管理入口是侧边栏那个仅管理员可见的 HA-MCP 面板，工具开关、feature flags、备份和主题都在那里。

实际使用中的坑

GitHub Issue 里评论最多的一批问题目前都标成已解决，下面几条是出现频率较高的。

• 写入超时（ClientDisconnect）。在 add-on 加 mcp-proxy、不走 TLS 的组合下，创建或编辑仪表盘、自动化、helper 会间歇性超时。79 条评论，已解决。
• Webhook Proxy 的 OAuth 2.1（beta）元数据找不到。根 PRM 被 HA 核心原生 OAuth 遮蔽，结果是 claude.ai 这类远程客户端 OAuth 失败。46 条评论，已解决。
• 大数据量调用超时。ha_get_device 与 ha_search 这类调用在客户端约 4 分钟后稳定超时。37 条评论，已解决。
• 升级后服务器起不来。升到 v7.13.0 之后 MCP 无法启动，删除重装也不见效。33 条评论，已解决。

与远程访问相关的还有两条：Tailscale Funnel 暴露时 Claude.ai 拒收旧 OAuth 模式签发的令牌，Zoraxy 加 ipv64 的反代组合下 claude.ai 连接器零入站请求。这两条同样已经关闭。Windows 上的安装失败也在 Issue 里出现过，同样是已解决状态。

和同类放在一起看

下面三行是同方向的 MCP 服务器，放在一起给选型做参照。对比项的部署细节和完整功能面没有在给定素材里说明，未逐一核实的部分按未核实写。

这三行里 ha-mcp 的体量最大，代价也最明显。它要跑进 Home Assistant 进程，工具数量多、写操作面广，你只想让 AI 读几个实体的时候，它比 hass-mcp 这类只做控制与查询的方案重得多。反过来说，要 AI 真的替你改仪表盘和自动化，ha-mcp 的覆盖范围才够。选型之前先想清楚要不要给写权限。

适合谁

已经在跑 Home Assistant、又想用 AI 客户端直接改自动化或仪表盘的人，这个项目的覆盖面够用。它把服务器塞进 HA 进程，不用单独维护一个常驻服务，也不需要手动管访问令牌，这是它相比外部安装路线省事的地方。

只打算让 AI 读几个传感器、不需要写操作的人，装一个带 87 个工具、能改仪表盘和自动化的集成属于用大件干小活，同方向里有更轻的选择。用 Home Assistant Container 或 Core 的人要注意，app 那条路走不了，得接受 Docker 或 PyPI 加令牌的配置量，也就失去了不用管令牌这个便利。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。