分类： 智能家居｜难度： 入门｜类型： 实操教程｜软件： HA-MCP
标签： 开源、Home Assistant、MCP、Claude、智能家居｜预计阅读： 约 9 分钟
一、这是什么
HA-MCP 是一个开源项目，全名 Home Assistant MCP Server，作用是把 Home Assistant（简称 HA，全球最流行的开源智能家居平台）接进 Claude、ChatGPT 等 AI 助手，让你用一句话就能控制和设定家里的智能设备。
2026 年 11 月 11 日，HA-MCP 登上 GitHub 当日热门榜第 7 名，核实时已有约 6,670 个 star，当日新增约 790 个，fork 约 430 个。仓库建立于 2025 年 9 月 14 日，采用 MIT 开源协议。
它一共提供 87 个工具，分成搜寻、控制、管理、监控、系统、弹性 6 大类：可以查设备状态、开关灯和家电、建立和修改自动化、新增仪表板卡片、查看自动化执行记录、备份和更新系统。支援 Claude、ChatGPT、Cursor、Copilot 等 15 种以上 AI 客户端。
跟 Home Assistant 内置的 MCP Server 不同：内置版本只能控制已经开放给语音助手 Assist 的设备；HA-MCP 则可以建立和编辑自动化、脚本、场景、仪表板，还能读取执行记录来除错、做备份和管理装置，是一套真正能「帮你打理智能家居」的工具。
它适合这些人：家里已经装了 Home Assistant，想用说话代替点按来控制设备的人；写自动化写到头痛，想直接叫 AI 帮手生成和除错的人；以及想先试试 AI 管家是什么感觉、手边还没有 Home Assistant 的人——项目提供一键演示环境，不用自己的 HA 也能试。
二、开始前先确认
- 先有一个 Claude 帐号：演示环境用的是 Claude Desktop，免费帐号就可以，先去 claude.ai 注册并登入。想用 ChatGPT 或其他客户端也可以，文末的 Setup Wizard 会按你的客户端生成设定。
- 演示环境不用自己的 Home Assistant：如果你只是想试试效果，下面的步骤 1 一条指令就能接通项目提供的演示环境，几分钟就能体验。
- 正式使用需要 Home Assistant 2026.8.0 或更新版本：HA-MCP 的整合安装要求 HA 2026.8.0 以上。版本太旧的话，先在 Home Assistant 里完成系统更新。
- 长期访问令牌要自己保管好：正式安装时要建立一组长期访问令牌（long-lived access token），外泄的话任何人都能从任何地方操作你的智能家居。建议按官方做法，另外开一个专用帐号给 HA-MCP 用。
- 演示环境不要接真实设备：一键安装指令预设连接的是项目提供的演示环境，里面是假设备，只适合体验；要控制自己家里的设备，一定要走步骤 2、步骤 3 的正式安装。
三、操作步骤
步骤 1：先试演示环境——一条指令接通 Claude Desktop
不用自己有 Home Assistant，也能先体验 HA-MCP。按你的电脑系统，选其中一条指令执行。
macOS：先去 claude.ai 登入免费帐号，然后打开终端机，执行：
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh
Windows：先去 claude.ai 登入免费帐号，然后打开 Windows PowerShell，执行：
irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex
Linux：先去 claude.ai 登入免费帐号，安装社群版 Claude Desktop for Linux，然后在终端机执行：
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
装好之后，下载 Claude Desktop（如果已经装了就完全退出再重开），然后直接问 Claude 一句：
Can you see my Home Assistant?
Claude 如果能列出演示环境里的设备和状态，就代表接通成功。Linux 用户如果想用官方命令列版 Claude Code：先安装 Claude Code，执行 curl -fsSL https://claude.ai/install.sh | bash，再执行 curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code，启动 claude 后输入 /mcp 确认，之后同样问一句 "Can you see my Home Assistant?" 就可以。
图 1：在终端机执行一键安装指令，接通演示环境。图片为 AI 生成的操作示意图，实际界面以终端机输出为准。
步骤 2：在自己的 Home Assistant 安装 HA-MCP 整合
试完演示、决定正式使用，就在自己的 Home Assistant 里安装整合。注意：同一时间只用一种安装方式，不要同时装整合和 Docker 等其他方式。
- 安装整合：Home Assistant 2026.8 至 2026.10，打开 HACS，搜寻 HA-MCP，按 Download；Home Assistant 2026.11 或更新版本，打开 设定 → Marketplace，接受首次使用提示，搜寻 HA-MCP，按 Install。HA-MCP 已收录在预设目录，不用另外连接 GitHub 或加入自订仓库。
- 重启 Home Assistant：安装完成后重启一次。
- 准备帐号和令牌：建议另外开一个专用帐号：设定 → 人员 → 新增人员，开启 允许登入、仅限本地访问，并设为 管理员。然后用这个帐号建立长期访问令牌：点右下角个人档案 → 安全性 → 长期访问令牌 → 建立令牌。也可以直接用自己的帐号建令牌，但令牌外泄时风险较大，官方建议用专用帐号。
图 2：在 Home Assistant 安装 HA-MCP 整合并建立长期访问令牌。图片为 AI 生成的操作示意图，实际界面以 Home Assistant 画面为准。
步骤 3：加入整合、复制链接网址，贴进 AI 客户端
- 打开 设定 → 装置与服务 → 新增整合，搜寻 HA-MCP，选择 HA-MCP Server。
- 贴上步骤 2 建立的长期访问令牌（或输入专用帐号的用户名和密码，HA-MCP 会自动建立令牌），选择客户端的连接方式：透过 Home Assistant 远程访问（先选 Secret URL，最简单）或 网络访问：本地网络，然后按 提交。两种方式预设都是关闭的，在其他装置上的客户端需要开启其中一种才能连接。
- 到整合的 Configure 画面复制连接网址。远程连接的网址格式是
https://<你的 HA 域名>/api/webhook/<webhook-id>（经 Nabu Casa 或已指向 Home Assistant 的反向代理）；同一网络内也可以用http://<HA 主机>:8123/api/webhook/<webhook-id>，或直接用http://<HA IP>:9584/private_<随机字符串>。 - 把这条网址贴进你的 AI 客户端（Claude Desktop、Claude.ai、ChatGPT 或其他支援 MCP 的客户端），就完成了。不同客户端的贴法不一样，可以打开项目的 Setup Wizard，它支援 Claude Code、Gemini CLI、ChatGPT、Open WebUI、VSCode、Cursor 等 15 种以上客户端，会按你的选择生成专用的设定。
步骤 4：动动嘴管理智能家居
接通之后，不用再记菜单路径，直接用自然语言跟 AI 说。官方给出的例子：
- 「Create an automation that turns on the porch light at sunset」——建立一个日落时自动开门廊灯的自动化，触发条件和动作由 AI 按规范生成。
- 「Add a weather card to my dashboard」——在仪表板上加一张天气卡片。
- 「The motion sensor automation isn't working, debug it」——分析自动化的执行记录，找出问题并给出修复建议。
- 「Create a script that sets movie mode: dim lights, close blinds, turn on TV」——建立一个「电影模式」脚本：调暗灯光、拉上窗帘、打开电视。
说得越具体，效果越好：讲清楚是哪个房间、哪盏灯、想在什么条件下触发。第一次建立自动化后，建议先去 Home Assistant 的自动化列表检查一次，确认触发条件和动作都符合预期，再正式启用。
图 3：向 Claude 说一句话，建立日落开灯自动化。图片为 AI 生成的操作示意图，实际界面以对话输出为准。
四、恢复办法
- Claude 回复看不到 Home Assistant：先确认安装指令确实执行完毕，完全退出 Claude Desktop 再重开；检查客户端里的 MCP 设定是否已写入 HA-MCP 的连接网址；演示环境用的是 stdio 连接，偶有连接问题的话可以重装一次安装指令。
- HACS 或 Marketplace 搜不到 HA-MCP：先确认 Home Assistant 版本是 2026.8.0 或更新版本；2026.8 至 2026.10 用 HACS，2026.11 或更新版本用 Marketplace；搜寻时也可以试「HA-MCP Custom Component」这个旧名字。
- 加入整合时提交失败：检查长期访问令牌是否贴错或已过期，重新建立一组再试；用专用帐号登入时，确认帐号已设为管理员、允许登入；重启 Home Assistant 后再试一次。
- 远程连不上、本地可以连：远程访问需要经 Nabu Casa 或已指向 Home Assistant 的反向代理；如果 Home Assistant 完全没有对外公开，可以改用本地网络连接，或参考官方文件的 OpenAI Tunnel 做法。
- AI 建立的自动化不如预期：先到 Home Assistant 的自动化列表检查触发条件和动作；直接告诉 AI 哪里不对，让它按你的要求修改；严重的话直接删除该自动化重新建立。
- 不想用了：在 AI 客户端移除 HA-MCP 的 MCP 设定即可；同时在 Home Assistant 的 设定 → 装置与服务 删除 HA-MCP 整合，并删除之前建立的长期访问令牌或专用帐号。
- 想从头再来：删除整合和令牌，重启 Home Assistant，再按步骤 2、步骤 3 重新安装一次；演示环境则重跑一次步骤 1 的安装指令。
五、注意事项（必读）
- 令牌等于你家的钥匙：长期访问令牌外泄的话，任何人都能从任何地方操作你的智能家居。务必用专用帐号、妥善保管，不要把令牌贴到公开地方。
- 先开只读模式试手：HA-MCP 提供只读模式开关、按工具开关和自动编辑备份。刚接通时可以先开只读模式，熟悉 AI 的操作方式后再放开写入权限。
- 自动化先检查再启用：AI 生成的自动化有机会触发条件写错，先检查一次再正式启用，特别是涉及门锁、暖气、洒水等设备的自动化。
- 只装一种服务器：整合内建的服务器本身就是一套完整安装，会取代应用程序（add-on）、Docker、uvx 等其他方式。同一时间只运行一种，不要同时运行两个，否则客户端可能连接卡住。
- 演示环境只是体验：一键安装指令预设连接的是演示环境，里面是假设备；要控制自己家里的设备，一定要走正式安装。
- 版本会变，以官方文件为准：本文的设定步骤适用于 v9.0.0（2026 年 10 月 28 日）及更新版本，个别安装界面和设定选项可能调整。遇到与本教程不一致的地方，以仓库 README 与官方文件为准。
- 不要直接贴令牌给 AI：连接网址本身含有 webhook 密钥，只贴进你信任的 AI 客户端设定里，不要贴到公开对话或群组。
六、官方资源链接
- GitHub 项目：https://github.com/homeassistant-ai/ha-mcp
- 官方文件站：https://homeassistant-ai.github.io/ha-mcp/
- Setup Wizard（15 种以上客户端设定）：https://homeassistant-ai.github.io/ha-mcp/setup
- Home Assistant 官方网站：https://www.home-assistant.io/
- Claude 官方网站：https://claude.ai/
七、常见问题
HA-MCP 是免费的吗？ 是免费开源的，采用 MIT 协议。演示环境也不用付费订阅，免费的 Claude 帐号就能试。但要注意：Claude Code 命令列版需要付费的 Claude 计划，Claude Desktop 免费帐号就可以用。
没有 Home Assistant 也能试吗？ 能。步骤 1 的一键安装指令连接的是项目提供的演示环境，里面是假设备，专门给没有 HA 的人体验。想控制自己家里的真实设备，就要走步骤 2、步骤 3 的正式安装。
一定要用 Claude 吗？ 不用。HA-MCP 支援 Claude、ChatGPT、Cursor、Copilot 等 15 种以上 AI 客户端，Setup Wizard 会按你选的客户端生成专用的设定。本教程以 Claude Desktop 为例，因为演示环境的安装指令是为它准备的。
HA-MCP 跟 Home Assistant 内置的 MCP Server 有什么分别？ 内置版本建基于语音助手 Assist，只能控制已经开放给 Assist 的设备。HA-MCP 则可以建立和编辑自动化、脚本、场景、仪表板、读取执行记录来除错、管理备份和装置，是一套能帮你「打理」智能家居的工具；如果只是想用说话开关灯，内置版本已经够用。
HA-MCP 会不会乱改我家里的设定？ 有可能——它提供的 87 个工具里包括建立、修改和删除自动化、仪表板、辅助实体等写入操作。所以刚接通时建议先开只读模式，自动化先检查再启用，重要操作前先备份。HA-MCP 每次编辑都会自动备份，出问题可以还原。
同一个客户端可以同时连两个 HA-MCP 吗？ 不可以。官方明确提醒：整合、应用程序、Docker、uvx 等只是同一套服务器的不同安装方式，每个客户端只能指向其中一个网址。同时保留两个入口是已知的连接卡住原因。
安装时说版本不支援怎么办？ HA-MCP 整合要求 Home Assistant 2026.8.0 或更新版本。先在 Home Assistant 里更新系统到最新版，再重新安装。
