ha-mcp：让 AI 助手真正"住进"你的智能家居

一句话故事

晚上十点，你对 Claude 说"我快到家了，把客厅灯调到 30%，空调提前打开"。Claude 没有听懂也没报错——它真的做到了。做到的背后，是 homeassistant-ai/ha-mcp 这个项目：它把 Home Assistant 的全部家底（设备、自动化、脚本、仪表盘、备份）翻译成了 87 个 AI 助手能调用的工具。

它从哪里来，解决什么问题

项目 2025 年 9 月创建，定位写得非常直白："The Unofficial and Awesome Home Assistant MCP Server"——非官方，但是目前生态里最完整的一个。仓库由个人开发者 Julien（julienld）主导，已发布到 PyPI（ha-mcp v8.7.0）和 MCP 官方 Registry（io.github.homeassistant-ai/ha-mcp），同时以 HACS 自定义组件、Home Assistant Add-on、Docker 镜像三种形态分发。

它要解决的是一个真实存在的断层。Home Assistant 自带的 MCP 集成基于 Assist 语音管线，约 15 个工具，只能控制"你暴露给 Assist 的实体"，读读状态、开开灯还行。而 ha-mcp 的定位是系统管理员：创建自动化、编辑 YAML、追踪失败脚本、管理仪表盘、备份恢复、读日志、查统计——这些是 Home Assistant 官方 API 从不提供的能力。

类比：把它当成智能家居的"root 权限"

如果说 Home Assistant 是你家，Assist 集成是给访客的遥控器，ha-mcp 就是你交给管家的总钥匙。它把整套 Haus 自动化系统拆成 87 个带参数的接口，交给 AI 一个一个去调。你不需要写 YAML，只需要说人话。

更有意思的是它的"安全层"设计：除了设备控制，还有只读模式开关、按工具粒度的启用/禁用、工具安全策略（需要用户审批）、编辑前自动备份。项目在 SECURITY.md 里明确划了威胁模型边界——已认证的 MCP 客户端被视作可信主体，防御恶意客户端不在服务端职责内；python_transform 表达式沙箱防的是"手滑写出死循环"，不是对抗攻击者。这种坦诚的边界声明，在开源项目里并不常见。

87 个工具怎么分的类

AI 侧的集成也很现代：默认通过标准 tools/list 返回完整目录，但对不支持"延迟加载工具"的客户端（Claude Haiku、Gemini、OpenAI 兼容本地模型、Copilot CLI）提供了 ENABLE_TOOL_SEARCH=true 开关——基于 FastMCP 的 BM25 检索，把 87 个工具收敛成 4 个入口（ha_search_tools / ha_call_read_tool / ha_call_write_tool / ha_call_delete_tool）加几个置顶工具，小模型也能扛住。

上手门槛：三种路径，选一种

路径一：HACS 自定义组件（官方推荐）。在 Home Assistant 里通过 HACS 添加自定义仓库 homeassistant-ai/ha-mcp，重启，添加集成，粘贴长效访问令牌或建一个专用管理员账号（建议本地访问 + 管理员权限），再选择客户端接入方式——"通过 Home Assistant 远程访问（先用 Secret URL）"和/或"局域网访问"。这个方式把服务直接跑在 HA 进程内，HAOS、Supervised、Container、Core 四种安装形态全支持，功能完全一致。

路径二：Docker。仓库提供多阶段 Dockerfile（uv 构建 + Python 3.13 slim 运行，按 digest 锁定基础镜像）和 compose 样例，docker compose up 即可，端口 8086，用 ha-mcp-data 命名卷持久化配置与 OAuth 注册。

路径三：uvx / PyPI stdio。本地跑，服务端接 Claude Desktop，配置文件贴一下就能用。

三种方式互斥，只能选一个，官方文档反复强调"永远不要同时跑两个 ha-mcp 服务端"。

争议与局限

• "非官方"是护身符也是免责声明。项目自称 unofficial，与 Home Assistant 官方无隶属关系，长期维护依赖个人开发者的时间与精力，核心作者只有一位。
• 权限过于敏感。能读写配置 YAML、能列出文件、能触发重启与备份恢复。令牌一旦泄漏等同于交出智能家居控制权。项目建议专用账号 + 局域网限制，官方也承认客户端侧的提示注入攻击不在其防御范围内。
• 对客户端模型能力有隐性依赖。小模型面对完整工具表容易"看不见你的家"，需要手动开工具检索模式缓解。
• beta 工具仍在演进。文件读写、ha_config_set_yaml、仪表盘截图、自定义工具、YAML 读取等被标记为 beta 或在版本间迁移过（如 v7.3.0 把 ha_config_set_yaml 移入 beta）。

工程质量

代码规模相当可观：仓库共 2489 个文件、1779 个 Python 文件，其中测试目录 932 个 Python 文件，测试与业务代码比例接近 1:1。源码分 src/ha_mcp/（tools、auth、client、policy、settings_ui、transforms、visibility、dashboard_screenshot、resources、utils 等模块），HA 集成组件单独放在 custom_components/ha_mcp_tools/。FastMCP 与 MCP SDK 被 vendor 进 _vendor/ 目录，以避免和 Home Assistant Core 自带的 mcp 1.x 版本冲突——这是个务实的工程取舍。

工程规范也很到位：AGENTS.md 作为 AI 编码助手的唯一权威指引（CLAUDE.md 只是软链），worktree 隔离分支开发流程、lefthook 提交钩子、Renovate 依赖升级、CodeRabbit 自动评审、lefthook/uv/ruff 配置齐全，还有 tests/haos_image_build 这样的 Home Assistant OS 镜像级测试。文档侧有独立 Astro 站点（site/）、docs/ 下 20+ 篇指南、SECURITY.md、PRIVACY.md、AGENTS.md，CHANGELOG 有 26 万字符，迭代非常勤。

行业意义

MCP 正在成为 AI 工具调用的事实标准协议，而"垂直领域 MCP Server"是它落地 IoT 的关键一环。ha-mcp 展示了一条可复制的路径：把某个成熟系统的全部深度能力封装成 MCP 工具集，配上安全策略层和多种分发形态，让通用大模型立刻具备该领域的专业操作能力。GitHub 上同类项目不少，但能把工具做到 87 个、测试覆盖到 932 个测试文件、还坚持维护文档站和隐私政策的，屈指可数。

对智能家居用户而言，它的意义是：不用再为每个自动化逻辑写 YAML；对话就是配置语言。对 AI Agent 开发者而言，它是一个近乎完美的参考实现——如何组织上百个工具、如何为小模型做工具检索降级、如何在权限设计上分层。