homeassistant-ai/ha-mcp
The Unofficial and Awesome Home Assistant MCP Server
📚 什么是 ha‑mcp？
ha‑mcp（Home Assistant 模型上下文协议服务器）是一个非官方但功能完整的服务器，允许大型语言模型助手（Claude、ChatGPT、Gemini 等）与 Home Assistant 实例进行交互。它实现了 模型上下文协议（MCP），使 AI 客户端能够：
- 查询任何实体（灯光、传感器、摄像头等）的状态。
- 控制设备，通过任何 Home Assistant 服务进行操作。
- 创建、编辑和调试自动化、脚本、仪表板、助手、区域、组、蓝图、HACS 插件、备份等。
- 读取日志、历史记录和自动化追踪，帮助 AI 排查问题。
- 切换安全功能（只读模式、工具级权限、自动编辑备份），以确保您对 AI 可能更改的内容保持控制。
简而言之，它将一个对话式 AI 变成了一个功能完整的 Home Assistant 管理员，不仅能开关灯，还能构建和维护您的整个智能家居配置。
🚀 如何运行？
ha‑mcp 可通过 四种方式 安装，所有方式均提供一个 AI 客户端可指向的单一 URL：
| 方法 | 运行位置 | 典型使用场景 |
|---|---|---|
| HA‑MCP 自定义组件（推荐） | 在 Home Assistant 内部作为自定义集成（通过 HACS 安装） | 适用于所有 Home Assistant 安装类型（OS、Supervised、Container、Core）。无需额外令牌。 |
| Home Assistant 应用 / 插件 | 作为 Home Assistant OS / Supervised 上的独立“应用”运行 | 适合希望使用独立进程但仍需内置 Webhook 实现远程访问的用户。 |
| Docker / PyPI / uvx HTTP 服务器 | 在 Home Assistant 外部（任意主机）运行 | 适用于无法运行插件的容器或核心安装，或希望将服务器部署在其他机器上的情况。 |
| 本地 stdio | 直接在您的笔记本电脑/台式机上运行（不推荐用于生产环境） | 快速演示或调试；存在已知传输问题。 |
所有方法都会生成一个秘密 Webhook URL（或直接本地端口），您需要将其粘贴到 AI 客户端的 MCP 配置中。
🔧 快速入门（自定义组件）
- 通过 HACS 添加集成 – 使用 README 中的徽章，或在 HACS 中添加仓库
https://github.com/homeassistant-ai/ha-mcp-integration作为自定义仓库。 - 重启 Home Assistant。
- 在 设置 → 设备与服务 → 添加集成 中，搜索 HA‑MCP 自定义组件，并添加 HA‑MCP 服务器 条目。
- 服务器启动后，打开其 配置 界面；Webhook URL（例如
https://my‑ha.duckdns.org/api/webhook/abcd1234）会显示，并且也会出现在 Home Assistant 日志中。 - 将该 URL 粘贴到您的 AI 客户端的 MCP 设置中 – 现在 AI 助手就可以与 Home Assistant 通信了。
该集成还添加了一个侧边栏面板，用于管理工具、功能开关、备份和主题，并支持启用可选的 Webhook 认证（ha_auth）。
🛠️ AI 实际能做什么？
ha‑mcp 提供了 87 个“工具”，按功能分组。README 中演示的一些常见操作包括：
| 类别 | 示例工具 |
|---|---|
| 控制 | ha_call_service, ha_bulk_control – 开关设备、调节气候等 |
| 自动化与脚本 | ha_config_get_automation, ha_config_set_automation, ha_config_get_script, ha_config_set_script – 创建或修改自动化和脚本 |
| 仪表板 / UI | ha_config_get_dashboard, ha_config_set_dashboard, ha_get_dashboard_screenshot – 添加卡片、编辑 Lovelace 布局 |
| 文件与 YAML (测试版) | ha_read_file, ha_write_file, ha_config_get_yaml, ha_config_set_yaml – 编辑原始配置文件 |
| 系统与维护 | ha_manage_backup, ha_manage_updates, ha_restart, ha_reload_core – 备份/恢复、更新 Home Assistant、重启服务 |
| 调试与监控 | ha_get_history, ha_get_logs, ha_get_automation_traces – 获取日志、查看实体历史、调试失败的自动化 |
| 安全 | ha_manage_security_policy, 只读模式切换 – 限制 AI 可更改的内容 |
当您要求 AI“创建一个日落时打开门廊灯的自动化”时，它会在后台调用相应的 ha_config_set_automation 工具，编写 YAML 并重新加载配置。
🌐 远程访问选项
- 内置 Webhook（由自定义组件使用） – 与 Nabu Casa、Cloudflare Tunnel 或任何反向代理兼容。
- Webhook 代理应用 – 用于插件方法，通过现有 Home Assistant Webhook 转发 MCP 流量。
- OpenAI Tunnel – 社区维护的隧道，允许 ChatGPT 风格的连接器在不暴露公共 URL 的情况下访问本地托管的服务器。
- OIDC 认证 – 可选模式，通过外部身份提供商（Keycloak、Auth0 等）保护 Webhook。
📦 演示与设置向导
该仓库提供适用于 macOS、Linux 和 Windows 的一键式演示脚本，可启动一个临时的 stdio 基础服务器，并连接到托管的演示 Home Assistant。运行脚本后，您可以向 Claude、ChatGPT 或任何 MCP 兼容客户端提问：“你能看到我的 Home Assistant 吗？”，以查看集成的实际效果。
还有一个基于网页的设置向导（https://homeassistant-ai.github.io/ha-mcp/setup/），可为所有支持的客户端（Claude Code、Gemini CLI、ChatGPT、VS Code、Cursor 等）生成精确的客户端特定配置。
🆚 与 Home Assistant 内置 MCP 服务器的区别
| 功能 | 内置 MCP 服务器 | ha‑mcp |
|---|---|---|
| 设备控制与状态查询 | ✅（仅对 Assist 暴露的实体） | ✅（所有实体） |
| 编辑自动化、脚本、场景 | ❌ | ✅ |
| 编辑仪表板 / Lovelace UI | ❌ | ✅ |
| 访问日志、历史记录、自动化追踪 | ❌ | ✅ |
| 管理助手、区域、组、标签 | ❌ | ✅ |
| 备份/恢复、应用管理、HACS、设备注册表 | ❌ | ✅ |
对于简单的语音风格命令，使用内置服务器；当您希望 AI 能够配置和维护整个 Home Assistant 设置时，请使用 ha‑mcp。
📚 更多学习资源
- 文档网站 – https://homeassistant-ai.github.io/ha-mcp/
- 设置向导 – https://homeassistant-ai.github.io/ha-mcp/setup/
- FAQ 与故障排除 – https://homeassistant-ai.github.io/ha-mcp/faq/
- GitHub 仓库 – https://github.com/homeassistant-ai/ha-mcp（问题、贡献指南、发布说明）
TL;DR
ha‑mcp 是一个真实、可投入生产环境的服务器，它将大型语言模型助手与 Home Assistant 桥接，赋予 AI 对整个 Home Assistant 配置的完全读写访问权限。通过 HA‑MCP 自定义组件（最简单路径）安装，获取生成的 Webhook URL，并将任何 MCP 兼容的 AI 客户端指向它——然后您就可以用自然语言让 AI 创建自动化、编辑仪表板、调试问题等。
相关
- 项目
- 项目
- 项目
- 项目
- 项目