ha-mcp

让 AI 直接控制你的智能家居，一句话搞定设备操作

ha-mcp 是一个非官方的 Home Assistant MCP 服务器实现，用 Python 编写，旨在通过 Model Context Protocol（MCP）将 AI 助手与智能家居平台无缝连接。它解决了 AI 无法直接控制或查询家庭设备的问题，为 LLM 提供了标准化的工具调用接口。核心能力包括：设备状态读取、设备控制（开关、调光等）、自动化触发、场景执行以及实体历史数据查询。通过 MCP 协议，AI 助手可以安全地与 Home Assistant 交互，实现自然语言控制家居。项目设计为即插即用，支持通过 HACS 或手动安装，并提供了清晰的配置指南。目前星标超过 4.3k，社区活跃，持续迭代中。

开源 free 开源模型

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 4819

维护状态活跃

是否开源是

定价模式 free

项目数据

分类开源模型

开发团队homeassistant-ai

所属国家

官网地址https://homeassistant-ai.github.io/ha-mcp

GitHubhttps://github.com/homeassistant-ai/ha-mcp

定价模式free

价格说明开源项目，MIT许可证，完全免费，无付费版本。

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型ai,claude,hacs,home-assistant,home-automation,llm,mcp,model-context-protocol

GitHub 星标★ 4819

30天Star增速

HF 下载量

上线时间2025-09-14 00:00:00

最近更新2026-09-22 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数4

使用教程

难度：入门约 20 分钟部署方式：本地安装 8 步

环境要求

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

安装与启动步骤

1选择安装方式

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

打开 HACS > Integrations > 右上角三点菜单 > Custom repositories，添加下方地址，类别选 Integration，然后下载。
```
https://github.com/homeassistant-ai/ha-mcp-integration
```
3或手动复制组件

不使用 HACS 时，把仓库中的 custom_components/ha_mcp_tools/ 整体复制到 HA 配置目录的 custom_components/ 下，路径按实际安装改。
```
cp -r custom_components/ha_mcp_tools/ /your/homeassistant/config/custom_components/
```
4重启 Home Assistant

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

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

非 HA 组件场景（Container/Core 或独立主机）可拉取官方镜像；完整启动参数与客户端配置需由 Setup Wizard 生成。
```
docker pull ghcr.io/homeassistant-ai/ha-mcp
```
7uvx 方式运行

用官方发布的 ha-mcp 包启动 streamable-HTTP 服务器；指向的 HA 地址与长期令牌同样由 Setup Wizard 生成。
```
uvx ha-mcp@latest
```
8配置远程访问

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

关键配置

配置项	必填	说明	示例
`Home Assistant URL`	是	服务器要连接的 HA 地址，由 Setup Wizard 写入客户端配置	`https://your-ha.example.com`
`长期访问令牌`	是	ha-mcp 调用 HA API 的凭证，在 HA 用户资料页生成	`eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.xxxxxxxx`
`MCP Server URL (remote)`	否	Webhook Proxy 启动后从 app 日志复制的远程访问地址	`https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx`
`mcp_server_url`	否	Webhook Proxy app 的可选项，用于转发其他外部 MCP 服务器	`http://homeassistant.local:8080/mcp`

如何确认成功

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

常见问题

Q：应该选 stdio 还是 HTTP？

A：README 明确提示 stdio 传输存在已知连接问题（issue #1713），仅建议演示或调试使用；正式环境请用自定义组件或 Docker / uvx 的 HTTP 方式。

Q：Home Assistant Container 或 Core 版能装吗？

A：Container / Core 无法运行应用商店的 app，需改用 Docker 或 PyPI/uvx 方式在外部主机运行服务器，再由客户端连接其 HTTP 地址。

Q：ha_config_set_yaml 找不到了？

A：v7.3.0 起该功能已移动到 beta，需参考 docs/beta.md 使用，属于破坏性变更。

Q：有 Nabu Casa 还需要暴露公网吗？

A：不需要。用同一商店里的 Webhook Proxy app 把 MCP 流量走现有 Nabu Casa 或反向代理即可，无需额外隧道或端口转发。

Q：ChatGPT 无法提供公网 URL 怎么办？

A：可参考社区 OpenAI Tunnel 集成，在 HA 内运行 OpenAI 的 tunnel-client，通过仅出站的连接接入，无需端口转发或公网地址。

注意事项

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

核心亮点

原生支持 MCP 协议，与 Claude、Cursor 等 AI 工具无缝集成
安装简单，支持 HACS 一键安装，配置门槛低
功能覆盖全面，支持设备控制、状态查询、自动化触发等

不足之处

非官方项目，稳定性依赖社区维护，可能滞后于 HA 核心更新
文档/社区待观察

适用场景

通过 AI 助手用自然语言控制家庭灯光、空调等设备
在智能家居中实现基于 AI 的自动化场景编排
开发基于 MCP 的智能家居语音交互应用

替代项目

Home Assistant 官方 Cloud 或 Assist 集成、node-red-contrib-home-assistant-websocket、OpenAI Home Assistant 插件

项目介绍

ha-mcp 是智能体领域的开源项目，由 homeassistant-ai 开发，2025 年首次发布。

在全站 13,090 个收录项目中，它的 GitHub 星标数（4,819）位列前 9%，在智能体分类的 2,517 个项目里位列前 10%。

近 41 天，它的 GitHub 星标从 4,369 增加到 4,819，净增 450。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-22。MIT许可证，完全免费，无付费版本。

它主要面向的使用场景是：通过AI助手用自然语言控制家庭灯光、空调等设备。同类可对比的替代方案包括 Home Assistant 官方 Cloud 或 Assist 集成、node-red-contrib-home-assistant-websocket、Op…。

上一篇：ai-agents-from-scratch

下一篇：mcp-server-chart