ha-mcp

环境要求

• 已安装并可访问的 Home Assistant 实例（组件/Core/容器均可）
• Home Assistant 的长期访问令牌（long-lived token）
• Docker 环境（仅选用 ghcr.io 容器方式时需要）
• uv 或 pip 环境（仅选用 PyPI/uvx 方式时需要）
• 一个支持 MCP 的 AI 客户端（Claude Code、Gemini CLI、ChatGPT、Cursor 等）

安装与启动步骤

1. 1选择安装方式

   README 给出四条路径：HA 自定义组件、Docker HTTP、PyPI/uvx HTTP、本地 stdio。真实使用推荐前三条，stdio 有已知问题。

2. 2添加 HACS 仓库

   打开 HACS > Integrations > 右上角三点菜单 > Custom repositories，添加下方地址，类别选 Integration，然后下载。

   https://github.com/homeassistant-ai/ha-mcp-integration

   复制

3. 3或手动复制组件

   不使用 HACS 时，把仓库中的 custom_components/ha_mcp_tools/ 整体复制到 HA 配置目录的 custom_components/ 下，路径按实际安装改。

   cp -r custom_components/ha_mcp_tools/ /your/homeassistant/config/custom_components/

   复制

4. 4重启 Home Assistant

   安装或复制完成后必须重启 HA，重启后集成才会出现在“添加集成”列表中。

5. 5添加集成条目

   在 HA 中进入 设置 > 设备与服务 > 添加集成，搜索 HA-MCP Custom Component，添加 HA-MCP File & YAML Tools 条目。

6. 6Docker 方式运行

   非 HA 组件场景（Container/Core 或独立主机）可拉取官方镜像；完整启动参数与客户端配置需由 Setup Wizard 生成。

   docker pull ghcr.io/homeassistant-ai/ha-mcp

   复制

7. 7uvx 方式运行

   用官方发布的 ha-mcp 包启动 streamable-HTTP 服务器；指向的 HA 地址与长期令牌同样由 Setup Wizard 生成。

   uvx ha-mcp@latest

   复制

8. 8配置远程访问

   已有 Nabu Casa 或反向代理时，从同一应用商店安装 MCP Server app 与 Webhook Proxy app，启动代理并按提示重启 HA。

关键配置

如何确认成功

集成添加成功后，HA 的设置 > 设备与服务 中出现 HA-MCP Custom Component；使用 Webhook Proxy 时，app 日志会打印 MCP Server URL (remote)，客户端能正常列出工具即成功。

常见问题

注意事项

• 本项目为非官方实现，使用前请确认与你的 Home Assistant 版本兼容。
• v7.3.0 存在破坏性变更：ha_config_set_yaml 已移入 beta。
• 客户端配置（Claude Code、Gemini CLI、ChatGPT、Open WebUI、VSCode、Cursor 等 15+ 种）建议直接用官方 Setup Wizard 生成，避免手写参数出错。
• 长期访问令牌属于敏感凭证，远程部署时建议配合 Webhook 密钥或 OIDC 认证，不要明文外泄。