homeassistant-ai/ha-mcp 是什么？

ha-mcp 是一个非官方的 MCP 服务器，让 Claude、ChatGPT 等 AI 助手通过自然语言操作 Home Assistant。本文梳理其四种安装方式、工具范围与权限模型，并指出它在多实例并发与 YAML 编辑上的现实限制。

homeassistant-ai/ha-mcp 可以商用吗？

可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。

homeassistant-ai/ha-mcp 还在维护吗？

在维护。仓库在最近一天内有新的提交。

homeassistant-ai/ha-mcp 是用什么编程语言写的？

主要是 Python（依据 GitHub 的语言统计）。

ha-mcp 安装与使用指南：Home Assistant 的 MCP 服务器解析

Q: homeassistant-ai/ha-mcp 还在维护吗？

在维护。仓库在最近一天内有新的提交。

秒懂

它是什么？: ha-mcp 是一个非官方的 MCP 服务器，让 Claude、ChatGPT 等 AI 助手通过自然语言操作 Home Assistant。本文梳理其四种安装方式、工具范围与权限模型，并指出它在多实例并发与 YAML 编辑上的现实限制。
适合谁用？: 适合已经熟悉 Home Assistant 且愿意接受非官方组件风险的用户。如果你主要用 Claude Desktop 或 ChatGPT 控制灯光、查询状态、执行自动化，ha-mcp 的 HACS 组件或 Add-on 能显著降低配置成本。
能商用吗？: 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
还在维护吗？: 在维护。仓库在最近一天内有新的提交。
用什么语言写的？: 主要是 Python（依据 GitHub 的语言统计）。

以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。

开源项目深度解析

Hysen Labs 编辑部 · 2026年9月10日 · homeassistant-ai/ha-mcp

它解决的问题：AI 助手与智能家居之间的协议断层

Home Assistant 提供 REST API 和 WebSocket，但每个 AI 客户端都要自己实现认证、状态查询和服务调用逻辑。ha-mcp 把这一层封装成 Model Context Protocol 服务器，让 Claude Desktop、Claude.ai、ChatGPT 等客户端通过统一接口对话。它面向的是不想为每个 AI 工具写定制集成的用户。项目自称非官方，但工具数量达到 87 个，覆盖设备控制、状态查询、自动化管理。注意，这个数字来自 README 的徽章，实际工具列表可能随版本变动。

四种安装方式，各自的服务生命周期

README 明确列出四种运行形态。HACS 自定义组件是首选，它把完整服务器跑在 Home Assistant 进程内，无需管理访问令牌，适用于 OS、Supervised、Container、Core 所有安装类型。Add-on 方式只支持 OS 和 Supervised，同样免令牌，适合本地网络内的 MCP 客户端。Docker 和 PyPI stdio 方式适合外部客户端，但需要自行处理令牌。关键约束是：四种方式彼此独立，同一客户端只能配置一种，否则会产生冲突。README 用粗体警告不要同时运行进程内服务器与其他安装。

连接 URL 的设计：webhook 与直连端口的取舍

安装完成后，配置界面会给出一个 webhook URL，形如 https://<你的域名>/api/webhook/<webhook-id>，这是为远程客户端准备的，可走 Nabu Casa 或任何已指向 Home Assistant 的反向代理。本地同一网络的客户端则可以直接访问 http://<ha-ip>:9584/private_<random>。这个随机后缀是安全凭证，URL 本身即密钥。如果你只想本地使用，可以在组件选项里关闭 Remote access via webhook，此时系统不会注册任何 webhook，但直连端口和侧边栏面板仍然工作。这种设计把网络暴露面分成两档，但用户必须理解 URL 泄露即等于控制权泄露。

工具权限模型：默认全开，细粒度控制靠 feature flags

ha-mcp 暴露 87 个工具，但 README 没有说明每个工具默认是否启用。它提到 File & YAML 编辑工具是 opt-in，默认关闭，且 ha_config_set_yaml 在 v7.3.0 被移入 beta。这说明项目对危险操作有意识，但普通工具如开关设备、执行服务是否默认全开，文档没有明确。侧边栏的 HA-MCP 面板提供管理工具、feature flags、备份和主题的功能，管理员可以在此调整。实际权限粒度取决于你花多少时间研究这些 flags。对于只有单一家庭用户的环境，默认全开可能够用；但如果你有多位家庭成员或敏感设备，需要仔细检查每个 flag 的后果。

认证机制：秘密 URL 与 ha_auth 的对比

默认情况下，连接 URL 中的随机字符串就是凭证，任何拿到 URL 的人都能控制你的智能家居。项目提供可选的 Webhook authentication 设置为 ha_auth，此时要求 Home Assistant 账号登录，替代秘密 URL 作为凭证。这是一个重要的安全升级，但 README 没有说明 ha_auth 是否支持所有客户端类型，比如 Claude Desktop 能否弹出浏览器登录。对于暴露到公网的 webhook，强烈建议启用 ha_auth。本地直连端口仍然依赖随机 URL，没有额外的登录层。这个不对称的设计需要用户自己权衡。

维护与升级成本：活跃开发与破坏性变更并存

仓库最后推送日期是 2026-09-09，最近三天内有多个 dev 版本发布，说明开发非常活跃。v7.3.0 引入了破坏性变更，将 ha_config_set_yaml 移至 beta，这意味着升级时可能遇到工具消失或行为变化。项目使用 FastMCP 构建，Python 版本要求见 pyproject.toml，但 README 没有给出具体版本号。E2E 测试工作流存在，但没有说明覆盖范围。对于依赖稳定 API 的用户，这种高频开发节奏意味着需要关注 release notes。HACS 组件和 Add-on 的升级路径不同，组件通过 HACS 更新，Add-on 通过 Supervisor 更新，两者都需要手动触发。

替代方案与定位差异

官方 Home Assistant 有原生的 Conversational Voice Assistant 和 Assist 管道，但那是为语音助手设计的，不是 MCP 协议。如果目标是让 Claude 或 ChatGPT 直接操作 HA，ha-mcp 是目前最直接的方案。另一个思路是使用 Home Assistant 的 REST API 自己写 MCP 服务器，但那需要维护认证、错误处理和工具定义，工作量远大于安装 ha-mcp。还有一个选择是等待官方 MCP 支持，但截至资料日期，没有迹象表明官方会很快提供。ha-mcp 的价值在于它把 87 个工具的开发生命周期集中到一个社区项目里，代价是你必须信任非官方维护者的更新节奏。

编辑结论

适合已经熟悉 Home Assistant 且愿意接受非官方组件风险的用户。如果你主要用 Claude Desktop 或 ChatGPT 控制灯光、查询状态、执行自动化，ha-mcp 的 HACS 组件或 Add-on 能显著降低配置成本。不适合对系统稳定性要求极高、希望每个工具都有独立权限审计的用户，因为其 87 个工具默认全部暴露，细粒度控制需要自行研究 feature flags。也不适合需要修改 YAML 配置的场景，该功能默认关闭且已移至 beta。采用前先验证三件事：你的 Home Assistant 版本是否支持 2026.2 之后的 Apps 界面，HACS 自定义仓库能否正常拉取 ha-mcp-integration，以及 webhook 地址在你的反向代理或 Nabu Casa 下是否可达。多实例并发问题尚未解决，生产环境务必只运行一种安装方式。

官方来源

社区笔记