发布日期:2026-11-17 | 适用版本:ha-mcp v9.2.0 | 要求:Home Assistant 2026.8.0+

ha-mcp 是一个基于 Model Context Protocol(MCP)协议的开源服务器,由社区开发者于 2025 年 9 月发布,让 Claude Desktop、ChatGPT、Cursor 等主流 AI 客户端通过标准化接口直接读写 Home Assistant 的完整配置层,包括设备控制、自动化管理、Lovelace 仪表板编辑、系统备份等共 86 个工具能力。截至 2026 年 11 月 17 日,项目在 GitHub 获得 7,909 颗 Star,当前稳定版 v9.2.0 于 2026 年 11 月 11 日发布。Home Assistant 2026.11 将 HACS 正式并入官方 Marketplace,ha-mcp 随之进入默认目录,安装门槛大幅降低,本周项目因此再次冲上 GitHub Python Trending。本文介绍 ha-mcp 的核心能力分层、四种安装方式的选型逻辑、真实操作场景演示(包括自动化创建、仪表板编辑、自动化调试),以及国内用户实现远程访问的三条可行路径,同时说明 v9.2.0 的关键变更和使用前的注意事项。


在这里插入图片描述

ha-mcp 能做什么

ha-mcp 的 86 个工具分为五大类:

控制层:调用任意 HA 服务(ha_call_service)、批量操作多个设备(ha_bulk_control)、实时查询实体状态。灯光、空调、窗帘、插座、传感器——任何已接入 HA 的设备都在范围内。

配置管理层:自动化的增删改查(ha_config_set_automation / ha_config_get_automation)、Lovelace 仪表板编辑、脚本和场景管理。这是 ha-mcp 最核心的差异化能力——AI 不只是控制设备,而是直接修改 HA 的配置文件。

监控层:查询历史记录(ha_get_history)、调取自动化执行 trace(ha_get_automation_traces,调试利器)、获取摄像头快照(ha_get_camera_image)。

系统层:备份与恢复(ha_manage_backup)、管理更新(ha_manage_updates)、重启 HA 实例(ha_restart)。

安全机制:Read Only Mode 一键切换(防止 AI 误操作)、per-tool 细粒度开关、每次编辑前自动备份。


四种安装方式怎么选

安装方式适用 HA 类型推荐程度特点
HACS / Marketplace 集成(推荐)全部类型★★★★★in-process 运行,零 token 管理,2026.11 起 Marketplace 一键搜索安装
App(Add-on)OS / Supervised★★★★☆无需 token,本地网络直连,不支持 Container/Core
DockerContainer / Core★★★☆☆灵活,需手动配 token 和环境变量
uvx / PyPI(stdio)任意(开发测试)★★☆☆☆有已知连接问题(issue #1713),仅推荐演示用

不要同时运行多种安装方式,会导致客户端连接挂起。

HACS / Marketplace 安装步骤(Home Assistant 2026.8.0+)

HA 2026.11 及以上:

  1. 进入 Settings → Marketplace,接受首次运行提示
  2. 搜索 HA-MCP,点击 Install
  3. 重启 Home Assistant
  4. 进入 Settings → Devices & Services → Add Integration,搜索并添加 HA-MCP Server
  5. 粘贴长效 token(在个人资料 → Security → Long-lived access tokens 生成)
  6. 在 Configure 页面复制连接 URL,粘贴到 AI 客户端配置中

HA 2026.8–2026.10:同上,第 1 步改为打开 HACS,搜索 HA-MCP 下载后安装。


在这里插入图片描述

实操演示:一句话完成三件事

以下是接入 AI 客户端后的真实交互场景:

场景一:创建自动化

用户:创建一个日落时自动开门廊灯的自动化

AI 调用 ha_config_set_automation,生成含正确日落触发器(sun.set 事件)和设备动作的 YAML,直接写入 HA 配置,重启生效。全程无需打开 YAML 编辑器。

场景二:修复不工作的自动化

用户:我的运动传感器自动化触发了但灯没开,帮我调试

AI 先调用 ha_get_automation_traces 拉取最近 10 条执行记录,分析 trace 中的条件判断分支,定位到"日出后时间条件"误判,给出修改建议并直接更新配置。

场景三:改仪表板

用户:把天气卡片加到我的主仪表板第一行

AI 读取当前 Lovelace 配置,在第一行插入 weather-forecast 卡片,保存并刷新——这是中文社区里流传的"Claude 一小时改完拖了几个月的面板"的原型场景。

场景四:批量操作

用户:把客厅所有灯调到 30% 亮度,色温暖白

AI 调用 ha_bulk_control,一次操作覆盖所有 light.living_room_* 实体,无需逐个调用。


国内用户的远程访问方案

ha-mcp 本身在局域网内运行,AI 客户端要从外网访问需要额外配置:

方案一:Nabu Casa(官方云服务)+ Webhook Proxy App
最简单,月费约 7 美元,HA 官方支持,连接 URL 自动生成。国内用户可直接访问 Nabu Casa 云端节点。

方案二:Cloudflare Tunnel
免费,无需公网 IP,配置一次即可。适合有路由器管理权限的用户。在 HA 中安装 Cloudflare Tunnel Add-on,将 ha-mcp 的本地端口(默认 9584)映射到 Cloudflare 域名即可。

方案三:OpenAI Tunnel(by @norpol)
专门解决 ChatGPT 接入问题。ChatGPT Connector 要求公网 URL,而这个社区方案通过出站连接建立隧道,不需要开放任何入站端口。在 HA 安装 hass-codex-tunnel-mcp 集成,配置 ha-mcp 本地 URL 即可。

ha-mcp 也支持通过标准 MCP 协议对接 AI 推理服务端。国内开发者如果希望在 AI 客户端侧统一接入多款主流大模型,七牛云 AI 推理服务提供标准 MCP 端点,可在同一个 MCP 客户端中同时管理 ha-mcp 和大模型连接(配置文档:developer.qiniu.com/aitokenapi/12984/mcp-user-manual)。


升级注意事项

v7.3.0 破坏性变更:ha_config_set_yaml 已移至 beta,默认关闭。如果你的工作流依赖这个工具直接写 YAML 文件,需要在 HA-MCP sidebar 面板中手动开启该 feature flag。

v9.2.0 新增:helpers 现在支持 HA Core 原生 helper flow,编辑输入辅助器(input_boolean、input_number 等)时会通过 Core 自带流程写入,而不是直接操作存储文件,兼容性更好。

只运行一个实例:HACS 集成、Add-on、Docker、uvx 四种方式不能同时运行,同一个 AI 客户端配多个条目会导致请求挂起。


常见问题

Q:没有 Nabu Casa,纯局域网能用吗?
完全可以。ha-mcp 安装后在局域网内默认监听 http://<ha-ip>:9584/private_<随机字符串>,AI 客户端和 HA 在同一局域网时直接填这个地址即可,不需要任何云服务。

Q:HA-MCP 操作会不会误删我的自动化?
ha-mcp 有两层保护:一是每次编辑前自动生成 HA 备份(可在 HA-MCP sidebar 查看);二是 Read Only Mode,开启后 AI 只能查询不能修改任何配置,适合先"让 AI 帮你审查"再决定是否执行。

Q:stdio 模式(uvx)和 HTTP 模式有什么实质区别?
stdio 模式在 ha-mcp 有已知传输问题(issue #1713),断连和挂起概率较高,官方明确不推荐用于正式环境。HTTP 模式(HACS 集成、Add-on、Docker)经过 E2E 测试,稳定性显著更好。如果你之前用 uvx 安装后遇到 AI 客户端偶发断连,切换到 HACS 集成通常能解决。


总结

ha-mcp v9.2.0 是目前功能最完整的 Home Assistant AI 控制方案,86 个工具覆盖从设备控制到系统备份的完整操作层。Home Assistant 2026.11 将 HACS 并入官方 Marketplace 这一更新,把 ha-mcp 的安装门槛从"手动折腾第三方源"降到了"搜索即装",这是本周项目再次冲上 GitHub Trending 的直接原因。如果你的 HA 实例已经升级到 2026.11,现在是接入的最好时机。

以上信息基于 ha-mcp v9.2.0(2026-11-11)及 Home Assistant 2026.11 官方文档,建议以 GitHub 仓库最新 README 和 HA 官方 Changelog 为准。


延伸阅读

  • ha-mcp GitHub 仓库:github.com/homeassistant-ai/ha-mcp
  • ha-mcp 官方文档与 Setup Wizard:homeassistant-ai.github.io/ha-mcp
  • 七牛云 Token Plan:qiniu.com/ai/plan
Logo

宁波官方开源宣传和活动阵地,欢迎各位和我们共建开源生态体系!

更多推荐