它是什么
HA-MCP 是一个用 Python 编写的开源 MCP（Model Context Protocol）服务器，作用是在 Home Assistant 和各类 AI 助手之间搭一座桥。装上它之后，Claude、ChatGPT 这类支持 MCP 的客户端就能直接“看到”你家里的实体、场景和自动化，并通过标准化的工具调用去查询状态、执行服务、修改配置。
项目基于 FastMCP 框架构建，目前对外暴露约 87 个工具，覆盖面从读取传感器数值到写入自动化规则都有。换句话说，它把原本需要手写 YAML、翻开发者工具页面的操作，变成了一句自然语言指令——“把客厅灯调暗一点，顺便看看明早的供暖计划”。
核心功能
- 87 个 MCP 工具：实体查询、服务调用、自动化与脚本管理、配置读写等常用操作基本都能覆盖。
- 进程内集成安装：推荐通过 HACS 或新版 Marketplace 安装 HA-MCP 集成，服务器直接跑在 Home Assistant 进程里，Home Assistant OS、Supervised、Container、Core 四种安装形态均支持。
- 客户端接入可控：安装流程会让你填写管理员访问令牌，并选择客户端可以如何连接，权限边界在配置阶段就定下来。
- 兼容主流 AI 客户端：Claude Desktop、ChatGPT 等支持 MCP 协议的助手都能对接，换客户端不必重搭后端。
- 带 E2E 测试的持续迭代：仓库配有端到端测试工作流和 beta 通道，实验性能力（如 YAML 写入工具）先走 beta 再转正。
适用场景
- 设备多、懒得点界面：家里几十个实体，想用一句话批量查询状态或批量开关。
- 不想碰 YAML：调整自动化触发条件、改场景动作时，让 AI 代写并校验。
- 移动/远程运维：手机上通过 AI 客户端快速排查“为什么灯没亮”。
- 折腾型玩家：想把大模型接进智能家居做更复杂的联动和语音交互实验。
上手建议
- 先看版本要求。README 标注需要 Home Assistant 2026.8.0 或更新版本，老系统请先升级再动手。
- 优先用集成方式装。在 HACS 里搜索 HA-MCP 下载，或在新版系统的“设置 → 应用市场（Marketplace）”里直接安装，之后重启 Home Assistant。这比手动跑容器省心得多，功能也完全对齐。
- 准备好管理员长期访问令牌，并在安装向导里想清楚客户端允许的连接方式——权限给大了方便，但也意味着 AI 能动的东西更多。
- 先只读、后写入。初期只让助手做查询和状态读取，确认模型理解正确后，再开放服务调用和配置修改。
- 注意破坏性变更。v7.3.0 起
ha_config_set_yaml被移入 beta，升级前先读 CHANGELOG，生产环境务必先备份configuration.yaml与自动化配置。
