HA-MCP Skill 技能

技能简介

HA-MCP（Home Assistant MCP Server）是一款开源的 Model Context Protocol（MCP）服务器，专门为 Home Assistant 智能家居平台提供 AI 集成能力。它由社区开发者维护（Stars 4653+，GitHub 地址 homeassistant-ai/ha-mcp），通过 MCP 协议让 AI 助手（如 Claude、ChatGPT）能够以自然语言方式控制家中的智能设备、查询设备状态、执行自动化服务以及管理 Home Assistant 实例。HA-MCP 基于 FastMCP 框架构建，目前已提供 87+ 种工具，覆盖灯光、空调、摄像头、自动化、脚本等常见智能家居场景。

核心能力

• 87+ MCP 工具：涵盖设备状态查询、开关控制、自动化管理、脚本执行、仪表盘操作等完整能力
• 多种安装方式：支持 HACS 自定义组件、Home Assistant 应用（add-on）、Docker 容器、PyPI/uvx pip 安装、本地 stdio 五种方式
• 自然语言交互：用户以日常语言描述需求，AI 自动转化为 Home Assistant 操作指令
• 零配置远程访问：通过 Nabu Casa、webhook 代理或 OpenAI Tunnel 实现外网访问，无需自行配置端口映射
• 本地优先安全：支持本地网络直连（http://ha-ip:9584/private_xxx），数据不出家门
• OIDC 认证支持：可对接 Authentik、Keycloak、Auth0 等身份提供商，支持多用户共享
• 多 AI 客户端兼容：Claude Desktop、Claude Code、ChatGPT、VSCode Copilot、Cursor 等均支持

安装配置

方式一：HACS 自定义组件（推荐）

1. 在 Home Assistant 中打开 HACS → Integrations
2. 点击右上角 ⋮ → Custom repositories，添加 https://github.com/homeassistant-ai/ha-mcp-integration（分类选 Integration）
3. 下载完成后重启 Home Assistant
4. 进入 Settings → Devices & Services → Add Integration，搜索并添加「HA-MCP Custom Component」

方式二：Home Assistant 应用（add-on）

1. 在 Home Assistant 中进入 Settings → Apps
2. 点击 Add repository，粘贴 https://github.com/homeassistant-ai/ha-mcp
3. 在 App Store 中安装「Home Assistant MCP Server」并启动
4. 在 Logs 标签页查看 MCP 连接 URL

方式三：Docker / PyPI（适用于独立主机）

# Docker 方式
docker run -d 
  -e HOMEASSISTANT_URL=http://your-ha:8123 
  -e HOMEASSISTANT_TOKEN=your_long_lived_token 
  -p 9584:9584 
  ghcr.io/homeassistant-ai/ha-mcp

# PyPI / uvx 方式
uvx ha-mcp@latest serve

使用步骤

1. 安装并启动服务器：选择上述任一安装方式，完成后获得 MCP 连接 URL（格式如 http://ha-ip:9584/private_xxx 或 webhook URL）
2. 配置 AI 客户端：在 Claude Desktop 等 AI 客户端的 MCP 配置中填入连接 URL
3. 验证连接：启动对话，输入「你能看到我的 Home Assistant 吗？」确认连接成功
4. 自然语言控制：用日常语言描述智能家居需求，例如：
   • 「晚上 10 点自动关掉所有灯」
   • 「把客厅空调调到 24 度」
   • 「创建一条日落时打开门廊灯的自动化」
5. 进阶使用：通过 AI 分析现有自动化的问题、创建或修改仪表盘卡片、管理脚本等

适用场景

• 智能灯光控制：语音或文字开关灯、调节亮度/色温、设置定时开关
• 暖通空调管理：控制空调、地暖、新风系统，查询当前温湿度
• 安防监控集成：查看摄像头画面、接收移动侦测告警、查看门锁状态
• 自动化调试与优化：让 AI 分析自动化执行日志，找出未触发原因并给出修复建议
• 仪表盘搭建：用自然语言让 AI 创建或修改 Home Assistant 仪表盘卡片
• 多品牌设备统一管理：Home Assistant 已接入数百个品牌设备，通过 HA-MCP 用统一界面管理

适用人群

• 已在使用 Home Assistant 的智能家居爱好者和技术用户
• 希望用自然语言管理智能家居，而不是打开多个 App 的用户
• 需要 AI 辅助调试和优化 Home Assistant 自动化的中级用户
• Home Assistant 开发者，想用 AI 加速脚本和自动化编写

工作原理

HA-MCP 本质上是一个 MCP 服务器，它将 Home Assistant 的 REST API 和 WebSocket 事件接口封装为标准化的 MCP 工具（tools）和资源（resources）。AI 客户端通过 MCP 协议发送工具调用请求，HA-MCP 将其转发为对应的 Home Assistant API 调用，并将结果以结构化数据返回给 AI。整个通信支持两种传输方式：本地 stdio（直接在进程内通信，适合 Desktop 应用）和 Streamable HTTP（适合网络远程连接）。AI 客户端无需知道底层 API 细节，只需以自然语言描述需求，HA-MCP 自动完成翻译和执行。

官方链接

• GitHub 仓库：https://github.com/homeassistant-ai/ha-mcp
• 官方文档：https://homeassistant-ai.github.io/ha-mcp/
• PyPI 包：https://pypi.org/project/ha-mcp/
• MCP 工具列表：https://homeassistant-ai.github.io/ha-mcp/tools/