HomeAssistantMCP 使用教程

📖 项目简介

Home Assistant 是开源的智能家居中枢，家里不同牌子的灯、插座、空调都可以接进去。它官方自带一个 Model Context Protocol Server 集成，把语音助手那套能力开放给外部的 AI 客户端。Codex 的官方说明里直接写了怎么接。

接上之后，你在 Codex 里说人话，它去读家里当前状态，再开关、调亮度、调温度。能碰到哪些设备，由你在「已暴露的实体」里勾选，没勾的它看都看不到。每次动手之前，Codex 会先问你要不要执行。

它给 AI 的就是语音助手那一套工具，外加一份只读的当前状态快照。所以「哪些灯还开着」这种问题它答得出。它不能替你新建自动化、改配置。那是另一类非官方服务的能力，本教程主路径不走那条。

📎 相关链接（点击展开）

官方集成文档（含 Codex 接法）：
https://www.home-assistant.io/integrations/mcp_server/

Codex 配置原文（写在文档的 Example: Codex 一节）：
mcp_oauth_callback_port = 12345
[mcp_servers.homeassistant]
url = "你家的中枢地址/api/mcp"
auth = "oauth"
oauth = { client_id = "http://127.0.0.1:12345" }
回调端口和 client_id 里的端口必须一致。client_id 是 Codex 本机回调地址，不要填成你家中枢的地址。

登录命令：
codex mcp login homeassistant

连上了但没有工具：
Codex 仓库 issue 11284。这时可改走非官方服务：在 GitHub 搜索 homeassistant-ai/ha-mcp，用 uvx 方式注册。官方这条通了就不必换。

更多教程：关注公众号 / 抖音 / 视频号「IT小圈」

✨ 核心亮点

💬

说人话，不用背口令

「我要睡了」「除了书房，其他灯都关掉」这种一句里带好几件事的话，语音音箱经常回没听懂。这里按你的原话拆开做。

✅

动手前先问你

Codex 调用工具前会列出要动哪些设备，你点确认才执行。

🔒

没勾选的碰不到

只暴露给语音助手的实体才能被读、被控。书房电脑这类不想给它的，不要勾。

📋

能读当前状态

官方提供一份只读的状态快照。先问「哪些灯还开着」，再决定关哪几盏。

🧩 它能做什么、输出什么

项目	说明
输入	自然语言。例如「我要睡了」「哪些灯还开着」「我出门了」。
适用类型	已经接到 Home Assistant、并且暴露给语音助手的灯、插座、空调、窗帘等。没接入中枢的电器它碰不到。
输出	调用语音助手那套工具：开关、调亮度、调温度，以及一份当前状态快照。不会在对话里生成新的自动化。
语言 / 兼容	提示词中文即可。官方文档写了 Codex、Claude、Cursor 等客户端的接法。本教程只写 Codex。
规格 / 容量	端点是 /api/mcp，协议是 Streamable HTTP。工具、提示词、资源都支持；采样和通知不支持。资源目前只在语音助手这条上提供。

🖥️ 环境要求

环境	建议配置
操作系统	跑 Codex 的电脑用 Windows、macOS、Linux 都行。中枢跑在你原来的设备上，不必为这一步换系统。
运行环境	一台已经在用的 Home Assistant，设置里加上 Model Context Protocol Server 集成。电脑上装好并登录 Codex。
硬件	不需要额外显卡。推理在 Codex 那边，控制发生在你家中枢。至少要有一盏已经接入中枢的灯，否则看不出效果。
低配方案	中枢只在家里局域网也能接：Codex 和中枢在同一网络，地址填局域网地址。官方也支持用长期访问令牌，不一定要走浏览器授权。
关键依赖	中枢里打开「允许控制」。只勾你愿意让它动的实体。Codex 配置文件能改、浏览器能打开中枢的登录页。

🚀 如何使用

💡

先在中枢里把集成加上、该暴露的设备勾上，再改 Codex 配置并登录一次。三步都通了，再说「我要睡了」。

在中枢里打开这个集成

进入 Home Assistant，添加集成，搜索 Model Context Protocol Server。打开「允许控制」。然后到已暴露的实体页面，只勾灯、插座、空调这些你愿意让它动的。文档地址在文末折叠块里。

                        text
                        添加集成 → Model Context Protocol Server → 允许控制 → 勾选要暴露的实体
                    

准备登录方式

Codex 走浏览器授权，一般不用提前建令牌。如果客户端不支持这种授权，就在中枢的个人资料里创建一个长期访问令牌，配置时作为访问凭证。令牌只放配置或环境变量，不要贴进聊天、不要拍进视频。

                        text
                        个人资料 → 长期访问令牌 → 创建（仅在不走浏览器授权时需要）
                    

写入 Codex 配置

打开 Codex 的 config.toml。要所有项目都能用，改用户目录里那份，不要只改某一个项目。文件最开头、任何表头之前，先写回调端口。文件末尾再加中枢这一段。地址换成你家中枢的完整地址，带端口。client_id 填本机回调，端口和第一行一致，前面要加协议头，不要填成中枢自己的地址。完整原文在文末折叠块。

                        toml
                        mcp_oauth_callback_port = 12345

[mcp_servers.homeassistant]
url = "你家的中枢地址/api/mcp"
auth = "oauth"
oauth = { client_id = "本机回调，端口 12345" }
                    

登录一次，再重启

如果配置写在某个项目目录里，先在这个项目打开一次 Codex，确认信任提示，然后退出回到终端。不想信任项目，就把配置写到用户目录。接着运行登录命令，浏览器里登录中枢并允许访问。完成后重启 Codex，或新开一个任务。

                        powershell
                        codex mcp login homeassistant
                    

用一句话试通

先说一句只读的，确认它真的看见了你家的设备。再说明确的动作。它列出要动的设备时，看清楚再点确认。

这三句分别在测什么：

说法	作用
哪些灯还开着	只读状态快照。答不对，先查实体有没有暴露，不要急着让它关灯。
我要睡了	复合指令：关一部分灯、留一盏暗的、调温度。动手前应先问你。
我出门了	把已暴露的灯和插座一起关掉。没勾上的设备不会动。

✅

通了的标志：它能报出还亮着的灯，并且关灯之前先列出名单等你确认。

🎯 典型应用场景

🌙

睡前收尾

一句「我要睡了」，客厅和走廊关掉，卧室留暗，空调调到指定温度。

🚪

出门检查

先问哪些灯还开着，再让它把不该留的关掉。

🎬

看电影

「客厅只留一盏暗的，其他灯关掉」。比背固定口令少一句「没听懂」。

🌡️

只调温度

空调已经暴露的话，直接说调到多少度，不用打开那个牌子的 App。

🔌

插座一起断

台灯、风扇接在已暴露的智能插座上时，出门那一句会连插座一起关。

👀

只看不动

问状态、不给确认，它就停在名单上。适合先核对再动手。

📈 和点 App、对音箱比

对比	差别
三个牌子三个 App	灯一个 App、空调一个 App、插座又一个。接进中枢之后，Codex 只对中枢说话，不逐个打开 App。
音箱固定口令	口令必须和设定句差不多，一句里夹「都关掉但留一盏」经常失败。这里把整句交给模型拆，再逐个调用已暴露设备的工具。
非官方的中枢 MCP	官方这条只能控制已暴露实体，不能新建自动化。要改配置、写自动化，才需要另找非官方服务。日常开关灯用官方这条就够。

🧠

视频里的灯灭画面是按这套接法生成的演示，不是作者家里的实拍。你自己接上之后，看到的是你家真实的灯。

❓ 常见问题

Q: 家里没有 Home Assistant，能直接用吗？

不能。这一步是把 Codex 接到你已经在跑的中枢上。电器还没接入中枢时，先把灯或插座接进去，再回来做这一步。

Q: 它能控制哪些设备？

只能控制你暴露给语音助手的实体。没勾的，它既不能读，也不能改。想缩小范围，就少勾几盏。

Q: 能帮我新建自动化吗？

官方这个集成不能。它暴露的是语音助手那套工具和一份状态快照，不包含改配置、建自动化。那种需求是非官方服务在做，不在本教程主路径里。

Q: 浏览器授权失败，或提示客户端不对？

client_id 必须是 Codex 的本机回调地址，端口和文件开头的 mcp_oauth_callback_port 一致。填成你家中枢的地址会失败。中枢如果套了反向代理，远程访问时用的主机名要和中枢网络设置里的内部或外部地址一致。

Q: 显示连上了，但是没有工具？

Codex 的 HTTP 型 MCP 有过这个问题，见仓库 issue 11284。先按官方步骤重试一次登录并重启。仍然没有工具时，再改用非官方服务走本地命令方式，搜索 homeassistant-ai/ha-mcp。官方这条一旦能列出工具，就不必换。

Q: 和家里的音箱有什么不同？

音箱吃固定口令，说复杂了就回没听懂。这里是 Codex 先理解整句，再调用中枢已经暴露的设备，并且动手前要你确认。

Q: 令牌和地址要不要给别人看？

不要。长期访问令牌等于你家中枢的钥匙。视频、聊天、截图里都不要出现令牌、公网地址和局域网地址。教程里用「你家的中枢地址」代替。

Q: 中枢只在家里的网络里，Codex 在外面能连吗？

官方这条要客户端访问得了那个地址。人在外面时，需要中枢本身已经能从外部打开（例如官方云）。人在家里、电脑和中枢同一网络时，填局域网地址即可，不必为了这一步再暴露到公网。

Q: 每次都要点确认，能关掉吗？

这是 Codex 调用工具前的确认，建议留着。关灯这种动作，看清楚名单再点，比省掉一次点击更值。

Q: 可以拿去接别人的家、拿来做项目吗？

集成随 Home Assistant 提供，协议以官方仓库为准。本教程只讲控制你自己已经接入的设备，不涉及代接、收费或批量给别人家装。