SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 更新于 2026-11-16

如何通过MCP将Claude连接到Home Assistant

Home Assistant自带MCP Server集成,按本文配置公网HTTPS访问、Claude自定义连接器和OAuth,并使用专用只读账户降低智能家居风险。

如何使用 MCP 将 Claude 连接到 Home Assistant

要使用 MCP 将 Claude 连接到 Home Assistant,请启用 Home Assistant 内置的 Model Context Protocol 集成,然后将其地址作为自定义连接器添加到 Claude。随后,Claude 会通过 Home Assistant 自己的 OAuth 登录流程进行身份验证。OAuth 是一种开放标准,可在不共享密码的情况下授予应用访问权限。Home Assistant 必须先拥有一个公开的 HTTPS 地址。配置该地址是整个过程的主要工作,因为 Claude 从 Anthropic 云端访问您的家庭网络,即使您使用的是 Claude Desktop。

MCP(Model Context Protocol)是一种开放标准,允许 AI 客户端调用另一台服务器上的工具。自 2025.2 版本起,Home Assistant 已提供 MCP Server 集成。这些工具可以读取家庭设备的状态,并可根据相关选项控制设备。因此,真正需要考虑的是安全性:哪些人可以访问您公开的地址?该地址背后的账户允许执行哪些操作?如果您还在评估 MCP 与其他扩展 Claude 的方式如何配合,请先阅读 MCP 与代理技能和规则文件的比较。

本指南已根据 Home Assistant、Anthropic、Tailscale、Caddy 和 Nabu Casa 的文档进行核对,日期为 15 November 2026。当日 Home Assistant 的当前版本为 2026.11.1。下面的若干选项发布仅几个月,因此请在开始前更新 Home Assistant。

Claude 为什么需要通过公网访问 Home Assistant

Anthropic 关于自定义连接器的帮助文章明确说明:“Claude 从 Anthropic 的云基础设施连接到您的远程 MCP 服务器,而不是从本地设备连接。”Home Assistant 文档对桌面应用也有相同说明:“即使您使用 Claude Desktop,Claude 也会从云端连接到您的 MCP 服务器。”

由此有两个要求。您的服务器必须能从 Anthropic 的 IP 地址范围通过公网访问。它还必须在标准 HTTPS 端口 443 上响应。因此,http://homeassistant.local:8123 永远不能作为连接器 URL 使用。Anthropic 的服务器无法解析只存在于您家庭网络中的名称,而端口 8123 也不是 443。

Claude Desktop 还提供另一种机制。claude_desktop_config.json 中列出的本地 MCP 服务器会使用您的本地网络。它们与连接器相互独立,在 claude.ai 或运行于云端的 Cowork 会话中不可用。Home Assistant 文档只介绍了 Claude Desktop 的连接器路径,因此本指南也使用该路径。

Claude Code 的工作方式不同。它运行在您自己的计算机或服务器上,并由自身建立 MCP 连接,因此该 URL 只需能从这台计算机访问即可。Home Assistant 指出:“Claude Code 只能通过 HTTPS 连接到 MCP 服务器。”因此,您自己网络中的私有 HTTPS 地址同样可用。Tailscale Serve 与 Tailscale Funnel 的区别正是这种选择:Serve 在您的 tailnet 中提供私有 HTTPS 地址,Funnel 则提供公网地址。

自定义连接器适用于 Free、Pro、Max、Ultra、Team 和 Enterprise 计划。Free 用户最多只能使用一个自定义连接器。这是Claude Free 计划包含的内容中介绍的限制之一。

启用 MCP Server 集成

  1. 在 Home Assistant 中,转到 设置 > 设备与服务,然后选择 添加集成。
  2. 从列表中选择 Model Context Protocol,并按照屏幕上的步骤操作。
  3. 转到 设置 > 系统 > AI。如果 Model Context Protocol 卡片显示 启用 按钮,请选择该按钮。
  4. 复制 主 URL。其路径为 /api/mcp。

完整的连接器 URL 由您的公网主机名和该路径组成,例如 https://ha.example.com/api/mcp。主机名取决于您在下文选择的访问路径。

默认公开的主 URL 内容

主 URL 有三个选项,这些选项仅适用于 /api/mcp。连接任何内容前,请先阅读以下说明。

  • 公开所有 AI 工具默认已启用。此时,主 URL 会公开所有工具集,包括集成稍后添加的工具集。其中一个工具集名为 Home Assistant。文档说明,它“可以读取所有实体、日志和历史记录,并执行任何操作”。
  • 要求管理员账户默认已启用。当主 URL 公开 Home Assistant 工具集时,无论此开关的状态如何,始终都需要管理员账户。
  • 只读默认未启用。启用后,主 URL 只会公开标记为不会更改任何内容的工具,例如获取家庭当前状态的工具。
  • 较旧的配置会将其中两个开关保持关闭。 对于“公开所有 AI 工具”,文档说明它“会保持关闭,以便客户端继续使用您选择的工具”。管理员开关“会保持关闭,以便客户端继续工作”。如果您的 MCP Server 条目早于这些选项,请打开其选项并检查开关状态。

关闭“公开所有 AI 工具”,即可逐个选择工具集。Device control 工具集会向 AI 提供与语音助手相同的工具,并且“只访问您向语音助手公开的实体”。Home Assistant 工具集没有此限制。

此外,还有面向单个工具集的独立 URL。/api/mcp/assist仅公开 Device control。这些 URL 会忽略上述三个选项。它们始终不是只读的。除 Device control URL 外,其他 URL 都要求管理员账户。

在信任 Device control 前,请检查它可以访问哪些内容。Assist 默认会公开新实体,其中包括 covers。Home Assistant 文档明确说明:“Covers 包括车库门和大门,因此 Home Assistant 也会自动公开它们。” Locks、alarm panels 和 scripts 不会自动公开。打开 Assist 的公开设置,移除任何您不希望聊天窗口打开的实体。

使用专用账户,而不是所有者账户

在 Claude 中选择 Connect 时,您会在浏览器中登录 Home Assistant。Claude 获得的访问权限属于您登录的账户。如果您使用所有者账户登录,Claude 就会以所有者身份运行,拥有所有者的全部权限。

在 Home Assistant 中创建一个单独的人员并为其设置独立登录,仅将其用于 Claude。以后要撤销 Claude 的访问权限时,只需删除这个账户,不会影响您自己的登录。然后选择以下两种配置之一。

范围较窄:Claude 控制少量设备。 将该账户保留为普通用户,不要设为管理员。在主 URL 选项中,关闭 Expose all AI tools,仅选择 Device control,并关闭 Require an administrator account。这样,Claude 只能访问已向语音助手公开的实体。如果 Claude 只需报告状态,也请启用 Read-only。您也可以改用 /api/mcp/assist,它不需要管理员权限。但该 URL 会忽略 Read-only 开关。

范围较广:Claude 读取日志和历史记录。 Home Assistant 工具集始终需要管理员账户。将专用账户设为管理员,但与所有者账户分开,并启用 Read-only。这样,Claude 可以读取实体、日志和历史记录,但不会公开可修改配置的工具。

在 Connect 步骤中,确认您登录的是哪个账户。在隐私浏览窗口中执行此步骤,可以降低误用所有者会话的风险。

不要依赖客户端中的审批提示来提供保护。在连接器流程中,Home Assistant 文档说明 Claude 在调用任何工具前会请求许可。Claude Code 的行为不同。从 v2.1.283 开始,auto mode 是交互式终端和 VS Code 会话的默认权限模式,而 auto mode 不会在每个操作前请求确认。无论客户端如何决定,Home Assistant 本身都会强制执行账户权限和 Read-only 开关。

Claude 的云端如何访问 Home Assistant?

本节其余内容是本指南根据各服务文档整理出的威胁模型。这些供应商都没有在文档中说明其路径无法防御哪些威胁,因此请将本节视为分析,而不是供应商声明。

下面每条路径都有一个共同点:任何能访问该 URL 的人都能访问 Home Assistant 的登录页面。因此请先设置登录保护。在 设置 > 系统 > 网络 的 HTTP 服务器 部分,启用 启用 IP 封禁。然后设置 封禁前的登录尝试次数。该设置接受 1 到 1000,仅在关闭“无限登录尝试”时显示。使用任何代理或隧道时,还应启用 信任 X-Forwarded-For,并将代理地址添加到 受信任的代理。Home Assistant 文档警告:“如果未设置这些选项,来自反向代理的请求会被阻止。”在 Home Assistant 2026.8 之前,这些设置位于 http: 的 configuration.yaml 块中。

Nabu Casa 的服务现在称为 Home Assistant Link(原名 Home Assistant Cloud)。2026 年 11 月 15 日,其定价页面列出的价格为每月 $6.50 USD 或每年 $65.00 USD,不含税。页面还列出了无需银行卡的 31 天免费试用。远程访问是列出的功能之一。

它暴露的内容:整个 Home Assistant Web 界面和登录页面,并通过公开的 HTTPS 地址提供访问。它无法防护的情况:Claude 所使用账户的密码过弱,或令牌从其他位置泄露。编写本指南时,Nabu Casa 的支持网站无法加载。请阅读其官方文档,了解其中继服务能够或不能看到哪些内容。

Tailscale Funnel

Funnel 将来自公网的流量路由到本地服务,Tailscale 表示所有套餐都提供该功能。它需要 Tailscale v1.38.3 或更高版本、MagicDNS、tailnet 的有效 HTTPS 证书,以及 tailnet 策略文件中的 funnel 节点属性。它只能监听 443、8443 和 10000 端口。Claude 需要使用 443 端口。如果这些要求对你来说比较陌生,什么是 Tailscale 以及 tailnet 如何工作会对此进行说明。在运行 Home Assistant 的计算机上执行:

sudo tailscale funnel 8123

Tailscale 会打印一个公开的 https://<machine>.<tailnet>.ts.net 地址,该地址代理到 http://127.0.0.1:8123。在连接器 URL 中使用该主机名。将 127.0.0.1 添加到 Home Assistant 的受信任代理,因为现在每个请求都来自本地 Tailscale 代理。按下 Ctrl+C 前,该命令会一直在前台运行。

它暴露的内容:整个 Home Assistant 端口,任何互联网用户都可以访问。Funnel 访问者不需要使用 Tailscale,因此你的私有 tailnet 不会为他们增加额外屏障。Funnel 流量还存在无法配置的带宽限制。

Cloudflare Tunnel

Cloudflare Tunnel 使用仅出站连接。网络内部的 cloudflared daemon 会向 Cloudflare 发起出站连接,因此无需开放入站端口,家中也不需要公网 IP。

它暴露的内容:你发布的主机名,整个互联网都可以访问,除非你在前面添加规则。要求用户先在 Cloudflare 登录的规则必须允许 Anthropic 发布的 IP 范围通过。Claude 的云端无法填写登录页面,因此其 MCP 请求会在 Cloudflare 处停止。将 cloudflared 访问 Home Assistant 时使用的地址添加到受信任的代理。

VPS 上的反向代理

使用此路径时,你可以控制面向互联网的服务器。一台具有公网 IP 的小型 VPS(虚拟专用服务器)运行反向代理,并通过 tailnet 等私有链路访问家中的 Home Assistant。家中的任何服务都不会暴露到互联网。你还可以限制哪些客户端能够访问该代理。

Anthropic 会发布其用于出站请求的 IP 地址,“例如调用外部服务器上的 MCP 工具时”。2026 年 11 月 15 日,该页面列出了两个 CIDR 格式的出站 IPv4 范围,没有列出出站 IPv6 范围。在设置当天,从 Anthropic 的 IP 地址页面复制当前范围。该页面还列出了已不再使用的旧地址,因此只应使用当前的出站地址。

在 VPS 上安装 Caddy 后,/etc/caddy/Caddyfile 可以丢弃所有不是来自这些范围的连接:

ha.example.com {
    @blocked not remote_ip <anthropic-range-1> <anthropic-range-2> 203.0.113.25
    abort @blocked
    reverse_proxy 100.101.102.103:8123
}

将 <anthropic-range-1> 和 <anthropic-range-2> 替换为 Anthropic 页面上的出站 IPv4 范围,将 203.0.113.25 替换为你自己的公网 IP,将 100.101.102.103 替换为 Home Assistant 在 tailnet 上的地址。列表中需要包含你自己的 IP,因为 Connect 步骤会在浏览器中打开 Home Assistant 的登录页面。该请求来自你,而不是 Anthropic。如果 Connect 停留在始终无法加载的页面上,说明列表中缺少你的地址。Caddy 默认设置 X-Forwarded-For、X-Forwarded-Proto 和 X-Forwarded-Host 标头,并代理 WebSocket 连接。只要该主机名的 DNS 记录指向 VPS,它还会为该主机名获取 TLS(传输层安全)证书。

caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

caddy validate 应在没有错误的情况下完成。从列表之外的地址执行时,curl -I https://ha.example.com/ 应完全收不到 HTTP 响应,因为 abort 会关闭连接。最后,将 VPS 的 tailnet 地址添加到 Home Assistant 的受信任代理。

它无法防护的情况:所有 Claude 用户共用 Anthropic 的 IP 范围。允许列表可以阻挡随机扫描器。任何获知你的 URL 并将其添加为自己连接器的人仍然可以访问你的登录页面,因此账户密码和 IP 封禁仍然重要。现在你还需要维护一台 VPS,及时安装补丁。

选择哪条路径

Nabu Casa 的配置最简单,也不需要自行维护服务器。Funnel 和 Cloudflare Tunnel 都无需在家中开放端口,但二者都会将完整的登录页面暴露在公网。VPS 代理的配置工作最多,但暴露面最小,因为只有 Anthropic 的 IP 范围和你自己的地址可以建立连接。无论选择哪条路径,专用账户和只读开关提供的保护都比路径本身更重要。

在 Claude 中添加连接器

  1. 在 claude.ai 中,打开 Customize > Connectors,然后选择 + Add > Add custom connector。在 Claude Desktop 中,Home Assistant 文档中的路径是 Settings > Connectors,然后选择 Add > Add custom connector。
  2. 将其命名为 Home Assistant,并粘贴完整 URL,例如 https://ha.example.com/api/mcp。
  3. 将 Authentication 设置为 Sign in now,将 OAuth client 设置为 Use Claude's published identity,然后选择 Add。
  4. 在新连接器的页面中,选择 Connect,并使用专用账户登录 Home Assistant。

如果使用 Team 或 Enterprise 计划,Owner 需要在 Organization settings > Connectors 下添加连接器。之后,每位成员都可以在 Customize > Connectors 下找到该连接器并选择 Connect,然后分别完成 Home Assistant 登录。

之所以选择已发布的身份,是因为这与 Home Assistant 处理 OAuth 的方式有关。Home Assistant 使用带 PKCE(proof key for code exchange)的 OAuth 2.0。它支持 OAuth Client ID Metadata Documents,因此会自动设置客户端 ID 和回调 URL。Home Assistant 不使用客户端密钥。它也不支持 RFC 7591 Dynamic Client Registration,文档指出,严格要求该功能的客户端“无法自动注册”。对于其他 MCP 客户端,文档指出,Client ID 必须是客户端应用程序的基础 URL,“绝不能是您的 Home Assistant 实例 URL”。

将 Home Assistant 添加到 Claude Code

claude mcp add --transport http home-assistant https://ha.example.com/api/mcp
claude mcp login home-assistant

claude mcp login 从 shell 中运行服务器的 OAuth 流程。在远程服务器上通过 SSH 会话运行时,也可以使用 --no-browser。默认情况下,claude mcp add 使用本地作用域,将服务器限制为本机上的当前项目。添加 --scope user 后,服务器可用于所有项目。在 Claude Code 中,/mcp 显示服务器是否已连接。如果 Claude Code 运行在 Linux 上且尚未完成设置,请参阅在 Linux 桌面和 CLI 中运行 Claude中的安装说明。

长期令牌还是 OAuth:旧版指南指的是什么?

旧版指南会要求您创建长期访问令牌。在这些指南编写时,这样做是正确的。Home Assistant 并没有在某个单独的版本中将令牌切换为 OAuth。这一变化分阶段完成:

  • 最初的 MCP Server 文档编写于 2025.2,其中写道:“目前,我们可以使用长期访问令牌来控制 API 访问。”
  • 从 2025 年 3 月 31 日起,文档开始介绍通过 IndieAuth 使用 OAuth。同时,文档也指出,部分 MCP 客户端支持访问令牌,但不支持 OAuth。
  • 使用 S256 方法的 PKCE 首次出现在 Home Assistant 的 2026.10.0 标签源代码中。在 2026.9.0 的源代码中没有该功能。
  • 当前的 MCP Server 页面不再提及长期令牌。

如果指南要求将令牌粘贴到请求标头中,说明它描述的是旧配置。请改用上文介绍的当前 OAuth 步骤。

何时选择社区 ha-mcp 服务器更合适?

ha-mcp 是一个采用 MIT 许可证的独立项目。其 v9.2.0 标签下的 README 列出了 87 个工具。默认分支上的 README 已经列出 86 个,因此工具数量会随构建版本变化。如果您需要比内置工具集更大、针对性更强的工具列表,并且能够接受不同的凭据模型,请选择 ha-mcp。

v9.2.0 推荐使用 HA-MCP 集成。它运行在 Home Assistant 内部,需要 Home Assistant 2026.8.0 或更高版本。在 2026.8 到 2026.10 期间,您需要通过 HACS(Home Assistant Community Store)安装。从 2026.11 开始,它位于 Settings > Marketplace。重启后,前往 Settings > Devices & services > Add Integration,添加 HA-MCP Server。该集成使用管理员权限运行,其文档建议使用专用的 HA-MCP 账户。该项目还提供 Docker 镜像、PyPI 软件包和 Home Assistant app(add-on);其 README 还介绍了仅用于测试的本地 stdio 模式。

固定使用稳定版本

截至 15 November 2026,最新稳定版本是 v9.2.0,于 11 November 发布。开发构建(.devN)会在每次推送到 master 后发布;在本次检查前的 24 小时内出现了 5 个开发标签。项目自身的说明很明确:“开发版本(.devN)可能包含错误。用于生产环境时,请坚持使用稳定版本。”请安装 v9.2.0 版本,不要安装 .devN 构建。Docker 镜像的 :latest 和 :stable 标签对应稳定版本,不会对应开发构建。如果您使用 uvx 运行它,README 中的命令以 @latest 结尾。请将其替换为 @9.2.0,因为 uv 的 @ 语法要求指定确切版本。PyPI 软件包需要 Python 3.13 或 3.14。

private_ URL 就是密码

内置服务器会要求 Claude 登录。ha-mcp 的主要模式不会。在您的网络中,其地址类似 http://<ha-ip>:9584/private_<random>。通过远程方式访问时,它是类似 https://<your-ha-domain>/api/webhook/<webhook-id> 的 webhook URL。项目文档说明“路径就是凭据”,并要求您“将 URL 当作密码处理:不要共享它,也不要将其粘贴到可能记录日志的位置”。任何获得完整 URL 的人都可以访问您的 MCP 服务器,中间没有登录页面。

这会改变威胁模型。将 URL 粘贴到共享聊天中,或让它出现在代理日志中,都会导致完整访问权限泄露。如果 URL 泄露,请生成新的 webhook ID 进行替换。在端点末尾添加 /readonly,即可建立隐藏写入工具并阻止写入调用的连接。远程访问可以通过 Nabu Casa 远程 UI,或通过您已运行的反向代理实现。对于 Cloudflare Tunnel,README 指向其 Setup Wizard。

ha-mcp 还提供标记为 beta 的 OAuth 模式。它仍会要求每个用户在同意表单中粘贴 Home Assistant long-lived access token。这与内置服务器的登录机制不同。

为什么连接器无法登录?

登录页面始终不显示,或者 Claude 提示无法连接服务器。 Anthropic 的云服务无法访问该 URL。请从家庭网络以外的网络通过 443 端口测试,并检查 allowlist(如果使用)。

通过代理登录时出现 OAuth 错误。 Home Assistant 文档指出,原因是缺少反向代理标头(X-Forwarded-Host、X-Forwarded-Proto),或者这些标头的值不匹配。文档还指出:“符合规范的 OAuth 客户端会拒绝此元数据。” Home Assistant 生成的 URL 必须与 Claude 使用的主机名和 scheme 完全一致。修复代理标头,并检查 Trusted proxies 设置。

对 /register 的请求返回 404。 客户端尝试使用 Dynamic Client Registration,但 Home Assistant 不支持此功能。在 Claude 中,将 OAuth 客户端设置为 Use Claude's published identity。

一个已知的未解决问题。 2026 年 11 月 15 日, issue #183050 报告 claude.ai 连接器在 Core 2026.11.0 上连接 /api/mcp 失败。该问题仍处于开放状态,并标记为需要更多信息,尚未确认修复方案。在依赖连接器之前,请先进行测试。

FAQ

Claude Desktop 会从我自己的计算机连接到 Home Assistant 吗?

对于自定义连接器,不会。Anthropic 和 Home Assistant 都说明,Claude 从 Anthropic 的云端连接,包括在 Claude Desktop 中也是如此。因此,Home Assistant 需要在 443 端口提供公开的 HTTPS 地址。例外是 claude_desktop_config.json 中的本地服务器和 Claude Code;它们从您自己的计算机发起连接。

Claude 可以通过 Home Assistant MCP 打开我的车库门吗?

可以,前提是账户和工具集允许此操作。Assist 默认会公开新的 cover。cover 包括车库门和大门,因此 Device control 工具集通常可以访问这些实体。Home Assistant 工具集可以执行任何操作。如果不希望 Claude 控制这些设备,请从 Assist 的公开范围中移除相应实体,或为主 URL 启用只读模式。

我还需要为 Home Assistant MCP 服务器创建长期访问令牌吗?

内置服务器不需要。当前文档使用带 PKCE 的 OAuth 2.0,没有提到长期访问令牌。令牌是 2025.2 首版文档中的方法。社区版 ha-mcp 服务器不同:其 beta OAuth 模式仍要求您粘贴长期访问令牌。

连接器多次失败后,我无法登录 Home Assistant 了。发生了什么?

IP 封禁阻止了登录失败的地址。Home Assistant 文档指出,最可能的原因是 OAuth 配置错误,例如客户端 ID 或 Home Assistant URL 错误。在 Home Assistant 配置目录中打开 ip_bans.yaml,删除被封禁地址对应的条目,然后重启 Home Assistant。再次尝试前,请先修正连接器设置。

这篇文章对您有帮助吗?

#claude#mcp#home-assistant#smart-home#remote-access