ha-mcp 接入 MCP 客户端的 5 个排错点

ha-mcp 接入 Claude、ChatGPT 等 MCP 客户端时，应按五层顺序排查：客户端能否连接、服务端能否被发现并列出工具、Home Assistant 身份与地址是否有效、目标实体和服务参数是否正确、自动化是否真正满足触发条件。工具列表为空，先查前两层；ha_get_overview 有响应但数据异常，先查 Home Assistant 身份和实体可见性；链路读通以后，再测试服务调用和自动化写入。

实际调用链是：用户请求交给模型，模型选择工具，MCP 客户端发送工具名和参数，ha-mcp 调用 Home Assistant，结果再返回给模型生成答复。 所以“模型回答不准确”和“MCP 根本没能调用工具”是两类问题。反复修改提示词之前，先证明各层能够完成对应操作，再开放 Home Assistant 写操作，比让模型反复试错更可靠。

MCP 客户端连不上或没有工具

先固定版本。安装方式、启动命令和配置字段应以官方 GitHub 仓库为准。 二手资料只适合用来辨认工具名称和调用链，不能拿其中不完整的部署说明拼接菜单路径或环境变量。 至少记录 Home Assistant、ha-mcp、MCP 客户端和操作系统版本；使用 Git 部署时，可以先查询仓库当前 HEAD，再把部署固定到该提交：

git ls-remote https://github.com/homeassistant-ai/ha-mcp.git HEAD

现有资料把 Home Assistant 自定义组件列为推荐方式，同时也存在独立运行的服务端形态，但资料没有给出完整安装段落。 因此不要把“支持 HACS”“能放进 Docker”和“所有客户端都能一键接入”混成一句话：自定义组件模式与独立 stdio 模式使用的配置不同，最终应按所选版本 README 中的入口、参数和环境变量填写。

本地 stdio 接入先检查 command、args、env 三项。不同客户端的 JSON 层级可能不同，但核对模板应接近下面这样：

{
  "mcpServers": {
    "ha-mcp": {
      "command": "<README 中的启动程序>",
      "args": ["<README 中的启动参数>"],
      "env": {
        "<README 中的 HA 地址变量>": "http://homeassistant.local:8123",
        "<README 中的 HA 长期访问令牌变量>": "<LONG_LIVED_ACCESS_TOKEN>"
      }
    }
  }
}

尖括号内容不是默认值，必须替换成当前 README 明确给出的名称，不能从其他 MCP Server 复制包名或密钥变量。先在运行 MCP 客户端的同一终端环境中，原样执行 README 中的启动命令，确认依赖可执行、目录有效且服务启动后没有立即退出，再交给客户端启动。Windows 是否需要 cmd /c 等包装，应由该客户端的执行规则决定，不能把其他 MCP Server 的做法照搬过来。

远程 URL 接入则要同时核对端点、传输方式和认证信息。SSE 与 Streamable HTTP 是不同传输，不能只看到一个 URL 就假设客户端与服务端能够协商成功；代理还可能改写路径、剥离认证头或把长连接缓冲掉。 若 ha-mcp 运行在容器里，检查必须在容器内部进行：浏览器能打开 Home Assistant，不代表容器里的 homeassistant.local 能解析，也不代表容器能访问 HA 的实际端口。

可以先用 Home Assistant REST API 做一个独立的可达性和凭据测试。

HA_URL='http://homeassistant.local:8123'
HA_TOKEN='<你的长期访问令牌>'

curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $HA_TOKEN" \
  "$HA_URL/api/"

能收到 HTTP 响应，说明至少已经越过 DNS、端口和 TLS 问题；超时通常仍应先查容器网络、端口和反向代理。这个测试只检查 HA 端点的可达性和凭据，不代表 MCP 工具已经被发现。

连接显示成功却没有工具时，依次检查服务端是否在初始化后退出、客户端是否加载了正确配置、工具发现请求是否完成，以及客户端是否禁用了该服务器。 应先核对 ha_get_overview、ha_call_service、ha_get_automation、ha_set_automation 这四个核心工具；资料中的“29 类、87 项工具”是特定版本的统计，不应当作永久不变的契约。

ha_get_overview 与 ha_call_service 调用失败

ha_get_overview 返回空数据时，先按返回路径分层检查，不要直接归因于模型不会提问。第一步是确认工具确实执行过，而不是模型根据上下文编造了一份空概览；第二步是确认 ha-mcp 使用的 Home Assistant 凭据有效；第三步才是检查在线域、实体总量、服务清单和自动化状态是否对当前身份可见。 “工具调用报错”“认证失败”和“调用成功但没有可见数据”分别对应不同层，混在一起排查会浪费时间。

调用 ha_call_service 时，参数必须符合当前工具说明。房间名、设备昵称和自然语言描述都不是实体标识，最终参数应来自工具 schema，并对应 Home Assistant 中真实存在的实体、域、服务和附加数据。灯光亮度与色温、扫地机器人的房间参数、媒体场景需要的字段并不相同。 调用前先核对客户端展示的 ha_call_service 参数定义，再按定义传入值，而不是让模型根据设备名称猜一份 JSON。

第一次写操作应选可逆、低风险实体。先读取状态，再对测试灯执行开关或亮度调整，随后在 Home Assistant 中确认状态确实变化并恢复原值。不要用门锁等不可逆目标验证“能不能调用”，媒体播放也不适合作为最小权限测试。

权限问题最好拆成四层检查：

工具列表可见，只说明客户端已经发现并加载了相应工具，不代表模型一定会调用，也不代表拥有执行权限。远程 MCP 一般还要把连接认证与被调用系统的数据权限分开考虑，但 Home Assistant 端采用什么认证方式，应以 HA 文档和 ha-mcp 当前实现为准，不能直接移植其他服务的 OAuth、JWT 或角色字段。

同一个配置在一个客户端正常、另一个客户端失败时，保留同一个只读请求，依次替换客户端、模型、认证头和传输方式。若更换客户端后恢复，重点比较 stdio 是否受支持、配置是否被客户端缓存、服务器是否启用以及认证头是否保留；若更换模型后恢复，再检查助手的工具调用策略。一次性同时换客户端、模型和账号，会让变量太多，失去排错价值。

自动化写入后的验证与回退

自动化操作应遵循“读取、预览、写入、读回、触发验证”的顺序。先用 ha_get_automation 读取目标规则，保存完整原 YAML、实体标识和触发条件；确认修改范围后，再用 ha_set_automation 写入。 模型回复“已经创建自动化”不算成功证据，写入后必须再次调用 ha_get_automation，确认规则确实落库。

规则已保存但不执行时，问题通常已经不在 MCP 链路，而在 Home Assistant 运行时。依次核对时区、时间触发、日落偏移、实体状态、附加条件和动作目标，再检查生成的 YAML 结构是否有效。 这类故障不必重新怀疑 MCP 连接；连接、工具发现和写入都已经成功，真正缺失的是触发条件或动作执行条件。

回退能力要以当前官方实现为准。资料提到测试变更可以回滚，但没有充分说明覆盖哪些修改。 因此写入前仍应保留原规则，并确认官方回滚接口能恢复哪些对象；不能根据测试环境的行为，承诺“生产自动化也能一键恢复”。Lovelace 看板等扩展写操作同样适用“读取、预览、写入、读回、回退”，但应与核心自动化排错分开处理。

最终验收包括七项：连接成功、四个核心工具可见、状态可读、低风险写入可执行、自动化能够读回、越权或错误调用能被拒绝、令牌没有进入日志。七项全部满足，才算完成接入，而不只是“客户端显示已连接”。