写自动化 YAML，可能是 Home Assistant 玩家里最高频也最磨人的需求。光触发器平台名（time、sun、state、numeric_state）就得来回查文档，写完还要肉眼对照缩进。11 月 12 日 GitHub Trending 上有一个项目直接把这个活交给了 AI：ha-mcp，一个 77 个工具的 MCP 服务器，让 Claude、Codex、OpenCode 这类编码 Agent 不只”控制设备”，而是直接读写 HA 的自动化、脚本、场景、仪表盘配置。我在 M4 Mac 上从零装了一套 Home Assistant + ha-mcp，让一个免费模型建了条真实的自动化，本文记录完整过程和几个官方文档不会告诉你的坑。
ha-mcp 是什么
项目本体在 GitHub 上以 MIT 协议开源，我写稿时 7,380 star，master 分支当天仍有提交。它基于 Python + FastMCP 构建，官方宣称 87 个工具。我在本机跑了它自带的 ha-mcp-smoke-test，实际发现 77 个——差了 10 个，这个差异下文会再说。它和 HA 内置的那个 MCP 服务器不是一回事：内置版只能调用已经暴露给 Assist 的服务，ha-mcp 多出来的能力都在”配置层”——创建/编辑自动化和脚本、管仪表盘、调 blueprints、读执行 trace 调试、管备份和 HACS。对想”一句话让 AI 帮我写自动化”的人来说，差的就是这部分。
工具覆盖面用官方 smoke test 的输出说话：从 ha_get_overview（AI 友好的系统总览）到 ha_config_set_automation（建自动化）、ha_get_automation_traces（调试执行轨迹）、ha_manage_backup（备份），43 个模块自动注册出 77 个工具。
实测环境与完整复现步骤
我的环境：M4 / 16GB / macOS 26.5.2，全部本地，不碰真实硬件——Home Assistant 的 demo 集成自带 6 盏灯、2 个开关、116 个实体，足够走完整条链路。
第一步：装 Home Assistant Core
不想动 Docker 的话，Core 版可以直接进 venv（Home Assistant 官方安装文档里 macOS 属于”高级玩法”，没有一键安装器）：
uv venv --python 3.14 ha-venv
uv pip install --python ha-venv/bin/python homeassistant
# 本机实测约 14 分钟，装完是 2026.11.1第一个坑在这里：老教程里的 hass --demo 参数已经不存在了，hass 会直接报 unrecognized arguments。demo 模式现在要写进配置文件：
# configuration.yaml
default_config:
demo:这样启动后 demo 集成会自动铺一套 116 个实体的假智能家居。
第二步：创建账号和长期 token
Core 版首次启动走 onboarding 流程，可以全程 curl 完成。注意 POST /api/onboarding/users 必须带 language 字段，不带会被 schema 校验直接打回（我就被打回过一次）：
curl -X POST http://localhost:8123/api/onboarding/users \
-H "Content-Type: application/json" \
-d '{"name":"Apisit","username":"apisit","password":"改成你的","language":"zh-Hans","client_id":"http://localhost:8123/"}'
# 返回 auth_code，再换 30 分钟有效的 access token：
curl -X POST http://localhost:8123/auth/token \
-d "grant_type=authorization_code&code=<auth_code>&client_id=http://localhost:8123/"access token 半小时就过期，而 ha-mcp 要的是长期 token。没有 UI 的话，用 WebSocket API 创建（auth 后发 {"id":1,"type":"auth/long_lived_access_token","client_name":"ha-mcp","lifespan":1825} 即可，我用十几行 Python 搞定，183 字符的 token 直接落盘）。
第三个坑（最疼的一个）：macOS 隐私权限直接把 HA 进程崩掉
上面这套配置我反复重启验证，HA 多次在启动一两分钟后被系统杀掉（exit 137），而且毫无征兆。查 home-assistant.log.fault 才看到真相——栈底一行：
__TCC_CRASHING_DUE_TO_PRIVACY_VIOLATION__原因是 default_config: 会拉起 bluetooth、dhcp、ssdp、zeroconf 这一组发现类集成。BLE 蓝牙栈（bleak → CoreBluetooth）和 DHCP 监听（aiodhcpwatcher → scapy）在无头终端环境里请求 macOS 隐私权限，TCC 弹不出授权窗，直接把进程 abort。在带 GUI 的会话里你会看到蓝牙授权弹窗，点允许就完事；在 SSH/无头/CI 里就是莫名其妙的反复死亡。
解法是把 default_config: 换成显式最小配置，手动点名自己真正需要的集成：
homeassistant:
frontend:
http:
auth:
api:
websocket_api:
config:
onboarding:
automation:
script:
scene:
recorder:
logbook:
history:
demo:换完之后 HA 重启只要几秒，稳如磐石。这里还连着一个小坑：最小配置里必须显式写 automation:，否则 automations.yaml 在启动时根本不会被加载——我第一版配置没写它，导致后面验证时自动化实体始终不出现，查了半天才发现是自己的锅。给 Agent 用的 HA 实例（尤其跑在 NAS、CI、无头 Mac 上）几乎都该用这种最小配置，顺手把蓝牙这个大坑一起绕掉。
还有个流程坑值得记一笔：pkill 掉旧 hass 之后它有几秒钟”垂死”时间，期间 8123 端口仍能应答 401，新起的实例绑定端口失败会静默退出。重启 HA 的正确姿势是确认端口真的释放（lsof -nP -i :8123 无输出）再启动。
第三步：装 ha-mcp 并直调验证
ha-mcp 要求 Python 3.14（requires-python = ">=3.14,<3.15"），同样一个 venv 解决：
uv venv --python 3.14 mcp-venv
uv pip install --python mcp-venv/bin/python ha-mcp
# 自检
env HOMEASSISTANT_URL=http://localhost:8123 \
HOMEASSISTANT_TOKEN=<长期token> \
./mcp-venv/bin/ha-mcp-smoke-test
# 输出：SMOKE TEST PASSED，Discovered 77 toolsHTTP 模式启动 ./mcp-venv/bin/ha-mcp-web，服务器监听 8086/mcp。我先不走 Agent，直接发 JSON-RPC 测最基础的链路：ha_search 搜 “light” 返回 7 个实体（6 灯 + 1 开关）全部精确命中；ha_call_service 开一盏灯，端到端 0.44 秒，返回里自带 "verified_state":"on"——ha-mcp 会回读执行结果做二次确认。我又用 HA 的 REST API 独立查了一遍，状态一致。这个”工具层验证 + 服务端独立验证”的双保险，比我之前测过的大多数 MCP 服务器都做得到位。
第四步：接上 OpenCode，让免费模型干活
OpenCode 的 MCP 配置只需一个 JSON 文件，HA 的 REST API 文档则在调试底层链路时帮了我不少忙：
{
"mcp": {
"ha-mcp": {
"type": "remote",
"url": "http://127.0.0.1:8086/mcp"
}
}
}给 Agent 的任务很简单：查家里有哪些灯、关掉卧室灯、创建”每天 7:30 打开厨房灯”的自动化。模型用 OpenRouter 上免费的 nemotron-3.5-lightning:free，全程 85 秒完成，0 花费。我从三个独立角度核实了它的工作是真实的：
light.bed_light状态确实是off（Agent 关的，REST 独立复核）；automations.yaml里落盘了一条完全正确的自动化——platform: time+at: "07:30:00"+light.turn_on指向厨房灯，id 就是让它起的morning_kitchen_lights；- 我先把厨房灯手动关掉，再手动触发这条自动化，HA 的历史记录清楚显示它在 10:10:00 把灯重新点亮——Agent 建的自动化在真实执行链路里生效了，不是”看起来创建了”。
一个小提醒：创建成功后自动化实体不会立刻出现在实体列表里，调一次 ha_reload_core（工具返回 “Reloaded 15 components”）或重启 HA 才完全生效。ha-mcp 的返回里会附一条提示让 Agent 自己去 reload，但免费模型不一定照做——你最好自己盯着这一步。
一个反转的 A/B 实验
ha-mcp 有个叫 tool search 的模式：开启后不把 77 个工具全量塞给模型，而是只暴露少数固定工具加一个 ha_search_tools 搜索入口，模型按需搜到工具名再用 ha_call_read_tool / ha_call_write_tool 代理调用。我做了个对照实验，同一个任务跑两遍：
| 配置 | 目录形态 | 轮次 | 输入 token | 输出 token | cache 读 | 耗时 |
|---|---|---|---|---|---|---|
| tool search 关（77 个全量） | 77 工具直调 | 15 | 28,931 | 2,104 | 129,952 | 65s |
| tool search 开 | 8 个入口 + 搜索代理 | 19 | 44,469 | 2,618 | 318,592 | 85s |
结果和我的直觉相反：开了”省上下文”的搜索模式，这轮任务反而更费——模型要多花轮次去搜工具再代理调用，每轮的上下文重复发送把省下的目录钱加倍还了回去。官方定位是”大幅降低空闲上下文”（挂机待命的场景确实省），但如果你是”一次性扔三件事给 Agent”的用法，全量目录直调反而更快更省。
顺带一个更有意思的发现：这个实验之前我还撞到过一次同一模型的”假失败”——它先试图向用户提问，被非交互模式拒绝之后，居然直接幻觉出”这套工具没有查实体、没有控灯的能力”，三项任务全部宣布放弃。换个时机重跑就完全正常。免费模型在 MCP 工具目录面前的稳定性方差是真实存在的，所以别因为一次翻车就否定工具本身，也别因为一次成功就相信它每次都行。
什么时候我不建议用
先说清楚边界。如果你只是想”回家自动开灯”这种固定需求，用 HA 原生 UI 点几下就够了，加一层 MCP 和 LLM 是纯开销。ha-mcp 真正的甜点区是这几类：已有几十条自动化想批量整理重构的存量用户；想用自然语言快速原型一条复杂自动化再手工精修的人；以及想给家庭系统做个”AI 值班员”的折腾党。另外 token 是有真实成本的——77 个工具全量暴露给每次对话并不便宜，tool search 模式挂机时才省，动手时未必。
还有两个我这次没有覆盖的路子，需要你自己判断：一是 HA Add-on / Docker 安装（官方推荐路径，进程内集成，比我这套 venv 更省心，但我为了轻量没走）；二是远程访问场景的 webhook 代理与 OAuth 配置，涉及公网暴露，建议先读它的 SECURITY.md 再动手。
未实测清单
以下部分我没有跑过，仅供参考：Claude Desktop / ChatGPT 客户端的实际配置体验（我只测了 OpenCode）；webhook 远程访问与 OIDC 认证；87 宣称与 77 实测差 10 个工具的确切原因（推测与版本或平台条件启用有关，待核实）；Zigbee/Z-Wave 硬件管理工具（无硬件）；备份恢复全流程。
小结
一条链路走下来，ha-mcp 是我今年测过的 MCP 服务器里完成度最高的一档：自带 smoke test、直调有执行结果回读、自动化创建后主动提示 reload、错误信息给到具体修法。macOS 无头部署的 TCC 崩溃坑是它自己的集成生态造成的，但解法明确（最小配置），付出十分钟就能避开。对 Home Assistant 存量用户来说，”AI 帮我写自动化”从演示视频走进自家客厅，差的只是这一个 venv 的距离。
延伸阅读：如果想给 Agent 补联网能力，可以看我之前测的Agent 联网能力层 Agent Reach；MCP 工具多的另一个解法是压缩，参考caveman 实测；给 Agent 搭本地沙箱环境还有floci 本地 AWS 模拟器和Lightpanda Agent 无头浏览器两条路；免费模型跑复杂任务的稳定性话题，Cloudflare security-audit-skill 实测里有更系统的数据。