HA-MCP：让 Claude 和 ChatGPT 管理 Home Assistant
一个让 Claude 和 ChatGPT 管理 Home Assistant 的 MCP 服务，覆盖 87 个工具并支持四种安装类型。
GitHub homeassistant-ai/ha-mcp 更新 2026-11-10 分支 master 星标 6.0K 分叉 293
Python Home Assistant MCP Claude ChatGPT HACS Home Assistant 2026.8+

🧭 决策指南

为什么现在热： 无法从材料判断。材料只显示 2026-11-10 当日新增 31 星、总星数 5,975，且最新版本为 Dev Build 9.2.0.dev3439，未说明具体关注原因。

适合，如果你

  • 你运行 Home Assistant 2026.8+，希望通过 HACS 安装 HA-MCP integration。
    README 的 Get Started 章节要求 Home Assistant 2026.8.0 或更新版本，并将 HA-MCP integration 作为推荐方式。
  • 你需要让 Claude、ChatGPT 或 Cursor 操作设备、自动化和脚本。
    README 的 Setup Wizard 列出 Claude Code、ChatGPT、VSCode、Cursor 等客户端，Features 列出设备控制、自动化和脚本工具。
  • 你需要通过 Remote access through Home Assistant 或 Local network 连接 AI 客户端。
    Get Started 第 4 步列出 Remote access through Home Assistant 和 Network access: Local network 两种连接方式。

不适合，如果你

  • 你的 Home Assistant 版本低于 2026.8.0。
    Get Started 明确写明 HA-MCP integration requires Home Assistant 2026.8.0 or newer。
  • 你要求 ha_config_set_yaml 处于稳定状态而不是 beta。
    README 顶部 Breaking change (v7.3.0) 写明 ha_config_set_yaml has been moved to beta。
  • 你不能接受管理员令牌泄露后从任何地方生效的凭据风险。
    Get Started 第 3 步说明 long-lived access token works from anywhere if it leaks。

前置条件

  • HA-MCP integration requires Home Assistant 2026.8.0 or newer。
  • 需要在 Home Assistant 中重启实例，然后添加 HA-MCP Server integration。
  • 需要管理员 long-lived access token，或为 HA-MCP 创建带 Administrator 权限的独立账户。
  • 需要在 Configure 页面获取 connect URL，并粘贴到 AI client。
  • 远程连接使用 Remote access through Home Assistant；同网连接可使用 Network access: Local network。

要注意

  • HA-MCP 的 Remote access 和 Network access 初始均为禁用。
    Get Started 第 4 步写明 Both start disabled。
  • 不要把自己的登录用于第二种账户方案，README 要求另建 HA-MCP 账户。
    Get Started 第 3 步建议创建独立账户，并写明 Never use your own login for the second option。
  • ha_config_set_yaml 已因 v7.3.0 breaking change 进入 beta。
    README 顶部 Breaking change (v7.3.0) 通知。
  • 恢复 Helper 时，实体 ID 冲突会在创建前拒绝，其他实体或设备注册表设置不会恢复。
    Features 中 Template helper edit backups 说明 collision 会被拒绝，且 Other entity/device registry settings are not restored。

材料未说明

  • README 节选没有给出 87 个工具的性能、延迟或并发限制。
  • README 节选没有说明 Claude、ChatGPT、Gemini CLI 等客户端的逐项版本兼容矩阵。
  • README 节选没有提供 HA-MCP integration 的升级迁移步骤或回滚流程。
  • README 节选没有说明 Remote access 使用 Secret URL 时的具体密钥轮换流程。
  • README 节选没有给出 Dev Build 9.2.0.dev3439 相比稳定版本的变更范围。

💡 深度解析

6
适合 我运行的是 Home Assistant 2026.8–2026.10 Container，习惯通过 HACS 安装组件，并希望在 Claude Code 中查询实体、修改自动化和管理脚本；HA-MCP 是否适合我的部署方式？
适合读者： 运行 Home Assistant 2026.8–2026.10 Container、通过 HACS 管理组件，并主要使用 Claude Code 的自动化维护者

适合，因为该集成明确支持 Container、HACS，以及 Claude Code 的连接配置。

  • README 要求 Home Assistant 2026.8.0 或更高版本，因此 2026.8–2026.10 满足版本门槛。
  • HA-MCP 集成在 Home Assistant 进程内运行，README 声明支持 Home Assistant OS、Supervised、Container 和 Core，并提供完整功能平行性。
  • 功能表包含 ha_config_set_automation、ha_config_set_script、ha_get_state 和 ha_search，覆盖发现、读取和配置修改。
  • 设置向导章节明确列出 Claude Code，并说明安装后需要重启 Home Assistant、添加 HA-MCP Server。

需要注意的是，HACS 下载本身不会完成服务配置；还要在“设置→设备与服务”中添加服务器。

  • Get Started：requires Home Assistant 2026.8.0 or newer
  • Get Started：works on every Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core
  • Setup Wizard for 15+ clients：Claude Code
  • Features / Complete Tool List：`ha_config_set_automation`、`ha_config_set_script`、`ha_get_state`、`ha_search`
材料未说明：提供的 README 片段没有说明 Claude Code 在 Container 环境下应使用本地网络、Webhook 还是其他连接方式。；未说明该版本组合下 HACS 安装后的具体认证界面和令牌存储位置。
视情况 我需要让 AI 修改自动化、脚本、仪表盘和 YAML，并在失败后恢复配置；其中 YAML 和仪表盘截图可以接受 beta，但我想知道 HA-MCP 是否适合做这类配置管理？
适合读者： 需要维护自动化、脚本、仪表盘和 YAML 的高级 Home Assistant 用户，尤其关心配置修改失败后的恢复边界

视情况，结构化配置管理较适合，但 YAML、截图和恢复边界意味着它不是完整的配置版本系统。

  • 工具表直接提供自动化、脚本、仪表盘和辅助实体的读写工具，例如 ha_config_set_automation、ha_config_set_script 和 ha_config_set_dashboard。
  • README 明确将 ha_config_get_yaml、ha_config_set_yaml 和 ha_get_dashboard_screenshot 标为 beta；其中 v7.3.0 已把 ha_config_set_yaml 移入 beta。
  • Safety 章节说明编辑会自动备份；辅助实体恢复还会检查配置入口身份、实体 ID 冲突并验证持久化选项。
  • 但 README 同时说明设备/实体注册表设置不会恢复，旧快照无法保留重命名后的实体 ID，冲突或验证失败后可能需要检查新建对象。

所以它适合 AI 辅助变更，不应被视为覆盖所有 Home Assistant 状态的事务性回滚系统。

  • Breaking change (v7.3.0)：`ha_config_set_yaml` has been moved to beta
  • Complete Tool List：`ha_config_set_automation`、`ha_config_set_script`、`ha_config_set_dashboard`、`ha_config_get_yaml`、`ha_config_set_yaml`
  • Features / Safety：automatic edit backups
  • Features：restoring an existing helper requires a fresh safety backup and verifies persisted options
  • Features：Other entity/device registry settings are not restored；older snapshots cannot preserve renamed entity IDs
材料未说明：README 片段没有说明自动备份的保存位置、保留数量或是否覆盖所有配置文件。；未说明仪表盘资源、YAML 文件和非辅助实体配置之间的恢复顺序及完整依赖关系。
视情况 我管理门锁、报警和摄像头，必须使用 Home Assistant 管理员权限才能接入 ChatGPT，但希望先限制为只读并对高风险操作要求审批；HA-MCP 是否适合？
适合读者： 管理门锁、报警和摄像头的 Home Assistant 用户，准备把管理员令牌交给 ChatGPT，但要求 AI 不能直接执行高风险控制

视情况，安全控制项匹配你的约束，但管理员令牌和高风险设备仍不能只依赖项目防护。

  • README 的 Safety 功能包含 Read Only Mode、按工具启用或禁用、tool security policies（user approval）和自动编辑备份。
  • 读取侧提供 ha_get_state、ha_get_history、ha_get_logs，摄像头还提供 ha_get_camera_image，可以先限制为查询和诊断。
  • 项目洞察明确提醒管理员令牌泄露后可从任何地方使用；自然语言误解仍可能影响门锁、报警、供暖或摄像头。
  • ha_call_service、ha_bulk_control 和 ha_restart 等工具具有实际控制或系统影响，不能因为启用了只读模式就假定所有客户端行为都一致。

如果组织要求独立的硬件级安全隔离，HA-MCP 不能单独满足该要求。

  • Features：Safety — Read Only Mode toggle, per-tool enable/disable, tool security policies (user approval), automatic edit backups
  • Complete Tool List：`ha_get_state`、`ha_get_history`、`ha_get_logs`、`ha_get_camera_image`
  • Complete Tool List：`ha_call_service`、`ha_bulk_control`、`ha_restart`
  • 项目洞察 user_experience.common_pitfalls：管理员令牌泄露后可从任何地方使用
  • 项目洞察 usage_limitations：不能替代对门锁、报警、供暖、电气设备或隐私摄像头操作的人工确认
材料未说明：README 片段没有说明只读模式是否会自动阻止所有写入、重启和服务调用工具。；未说明 ChatGPT 客户端是否完整支持项目的用户审批策略，以及审批提示如何呈现。
适合 我使用 ZHA 或 Z-Wave，排障时需要同时看设备状态、历史、自动化轨迹、系统日志和无线配置参数；HA-MCP 是否能减少我在多个 Home Assistant 页面之间切换？
适合读者： 使用 ZHA 或 Z-Wave、需要查询历史与自动化轨迹来排查间歇性故障的 Home Assistant 运维用户

适合，工具覆盖了你列出的主要诊断数据源，但它不能替代设备、无线网络或集成本身的故障修复。

  • Search & Discovery 的 ha_get_state 和 ha_get_overview 可用于先确认实体与系统概览。
  • ha_get_history、ha_get_automation_traces 和 ha_get_logs 分别覆盖历史、自动化轨迹和系统日志。
  • README 的 Monitor 表明确列出 History、statistics、automation traces 和 ZHA devices；工具清单也包含 ha_manage_radio。
  • 对 Z-Wave，README 说明 ha_manage_radio 支持 get_config_params 和 get_config_param，默认读取 Z-Wave JS cache，也可请求单个完整根参数的设备读取。

因此它能集中诊断上下文，但项目洞察明确指出，设备离线、无线网络不稳定或集成驱动缺陷不会由 HA-MCP 自动解决。

  • Features：Monitor — History, statistics, camera snapshots, automation traces, ZHA devices
  • Complete Tool List：`ha_get_state`、`ha_get_overview`、`ha_get_history`、`ha_get_automation_traces`、`ha_get_logs`、`ha_manage_radio`
  • README Z-Wave 段落：`get_config_params`、`get_config_param`；reads use the Z-Wave JS cache by default
  • 项目洞察 usage_limitations：不会自动解决设备离线、集成驱动缺陷或无线网络不稳定
材料未说明：README 片段没有说明 ZHA 查询能读取哪些具体诊断字段，以及是否支持修改 ZHA 参数。；未说明历史和日志查询的时间范围、数据量限制或对 Home Assistant 主机负载的具体影响。
视情况 我已经使用 Home Assistant 2026.11，想从 Marketplace 安装 HA-MCP，再让远程 ChatGPT 查询状态并控制设备；这个方案是否适合，而不需要自己维护额外代理？
适合读者： 已升级到 Home Assistant 2026.11、希望在 Marketplace 安装 HA-MCP，并从远程 ChatGPT 访问家庭实例的家庭自动化用户

视情况，安装路径很合适，但远程访问的认证和暴露边界决定了是否适合。

  • README 说明 Home Assistant 2026.11+ 可从 Settings → Marketplace 安装，HA-MCP 位于默认目录，不需要连接 GitHub 或添加自定义仓库。
  • 集成在 Home Assistant 内进程运行，设置时询问管理员访问令牌和客户端连接方式，因此不必单独部署 HA-MCP 代理。
  • 功能表包含 ha_get_state、ha_call_service 和 ha_bulk_control，满足 ChatGPT 查询与设备控制需求。
  • 项目洞察指出本地网络与经 Home Assistant/Nabu Casa 或反向代理的远程连接并存；README 也提醒远程连接、Webhook 和反向代理具有不同安全边界。

如果你不能明确限制远程 URL、认证方式和凭据保存位置，就不应直接开放控制工具。

  • Get Started：On Home Assistant 2026.11 or newer, open Settings → Marketplace
  • Get Started：HA-MCP is in the default catalog
  • Get Started：setup asks for an administrator access token and how clients may connect
  • Complete Tool List：`ha_get_state`、`ha_call_service`、`ha_bulk_control`
  • 项目洞察 user_experience.common_pitfalls：远程连接、反向代理、Webhook 和本地网络连接的安全边界不同
材料未说明：README 片段没有给出 ChatGPT 远程连接的完整配置步骤。；未说明远程 URL 是否强制额外认证、令牌如何轮换，以及客户端如何存储管理员凭据。
视情况 我使用 Ollama 这类本地小模型，不希望模型在 87 个工具中频繁选错；如果主要任务是搜索实体、读取状态和查询历史，HA-MCP 是否适合？
适合读者： 使用 Ollama 等本地小模型、需要在 87 个 MCP 工具中稳定完成实体发现和状态查询的 Home Assistant 用户

视情况，读取型任务适合，但小模型需要依赖工具发现能力或缩小工具目录。

  • README 列出完整工具清单共 87 个工具，范围从搜索到系统管理；对工具选择能力有限的本地模型而言，目录规模本身会增加决策复杂度。
  • Search & Discovery 提供 ha_search、ha_get_overview 和 ha_get_state，适合先定位实体再读取状态。
  • History & Statistics 提供 ha_get_history，可覆盖历史查询；项目洞察还指出支持基于搜索的发现。
  • README 的章节目录明确包含 “Smaller or local LLMs (Ollama, etc.)” 和 “Enable search-based discovery”，说明项目考虑了这类部署，但提供片段没有给出具体启用命令或默认配置。

因此它不是“小模型无需适配即可稳定使用”的方案，而是有针对性的工具发现路径。

  • Complete Tool List (87 tools)
  • Search & Discovery：`ha_search`、`ha_get_overview`、`ha_get_state`
  • History & Statistics：`ha_get_history`
  • README 目录：Smaller or local LLMs (Ollama, etc.)；Enable search-based discovery
  • 项目洞察 solution_analysis：搜索与发现是独立能力
材料未说明：提供的 README 正文没有说明 Ollama 支持的模型名称、最小上下文窗口或工具调用格式。；未说明搜索模式是否默认启用，以及如何按连接 URL 配置工具目录。

✨ 核心亮点

  • 87 个工具覆盖 Home Assistant 控制与配置
  • HA-MCP integration 支持四种安装类型
  • 兼容 Claude、ChatGPT 及 15+ 客户端
  • 项目已有 5,975 星但最新版本仍是 Dev Build

🔧 工程化

  • 用 ha_call_service 和 ha_bulk_control 控制设备与服务
  • 用 ha_config_set_automation 管理自动化与脚本
  • 用 ha_get_history 查看历史、统计和自动化轨迹
  • Read Only Mode 与工具安全策略支持审批控制

⚠️ 风险

  • 管理员令牌泄露后可从任何地方使用
  • Remote access 和 Network access 默认都禁用
  • ha_config_set_yaml 在 v7.3.0 已移入 beta
  • ha_restart、ha_manage_backup 等工具可改变系统状态

👥 适合谁？

  • 使用 Home Assistant 2026.8+ 的家庭自动化用户
  • 希望让 Claude 或 ChatGPT 操作 HA 的开发者
  • 使用 HA OS、Supervised、Container 或 Core 的用户
  • 需要接入 Claude Code、Gemini CLI 或 Cursor 的团队