如何將 Claude 連線至 Home Assistant MCP
啟用 Home Assistant 2025.2 以上內建 MCP Server,選擇安全的公開 HTTPS 路徑,再使用專用唯讀帳號限制 Claude 的存取權限。
如何使用 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 用戶端呼叫另一台伺服器上的工具。Home Assistant 自 2025.2 版本起提供 MCP Server 整合。這些工具可以讀取您家中裝置的狀態,並可透過適當的選項控制裝置。因此,真正需要決定的是安全性。誰可以連線至您公開的位址?該位址背後的帳號獲准執行哪些操作?如果您仍在評估 MCP 與其他延伸 Claude 的方式如何搭配,請先閱讀 MCP 與 agent skills 及 rules files 的比較。
本指南已於 15 November 2026 依據 Home Assistant、Anthropic、Tailscale、Caddy 與 Nabu Casa 的文件進行確認。當天的 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 使用者最多只能使用 1 個自訂連接器。這是Claude Free 方案包含的功能所涵蓋的限制之一。
啟用 MCP Server 整合
- 在 Home Assistant 中,前往 Settings > Devices & services,然後選取 Add Integration。
- 從清單中選擇 Model Context Protocol,並依照畫面上的步驟操作。
- 前往 Settings > System > AI。如果 Model Context Protocol 卡片顯示 Enable 按鈕,請選取該按鈕。
- 複製 Main URL。其路徑為
/api/mcp。
完整的連接器 URL 是公開主機名稱加上該路徑,例如 https://ha.example.com/api/mcp。主機名稱取決於您稍後選擇的存取路徑。
主 URL 預設會公開的內容
主 URL 有 3 個選項,而且這些選項只適用於 /api/mcp。在連接任何內容前,請先閱讀以下說明。
- 公開所有 AI 工具預設為開啟。此時主 URL 會公開所有工具集,包括日後由整合新增的工具集。其中一個工具集名為 Home Assistant。文件指出,它「可以讀取所有實體、日誌和歷史記錄,並執行任何動作」。
- 要求管理員帳戶預設為開啟。當主 URL 公開 Home Assistant 工具集時,無論此開關的設定為何,一律需要管理員帳戶。
- 唯讀預設為關閉。開啟後,主 URL 只會公開標示為不會變更任何內容的工具,例如取得住家的目前狀態。
- 較舊的設定會將其中 2 個開關維持關閉。 對於「公開所有 AI 工具」,文件指出它「會維持關閉,讓您的用戶端保留您選取的工具」。「要求管理員帳戶」則「會維持關閉,讓您的用戶端持續運作」。如果您的 MCP Server 項目早於這些選項,請開啟其選項並確認設定。
關閉「公開所有 AI 工具」,即可逐一選取工具集。Device control 工具集會提供與語音助理相同的工具給 AI,而且「只會存取您公開給語音助理的實體」。Home Assistant 工具集沒有這項限制。
此外,也有只對應單一工具集的個別 URL。/api/mcp/assist只會公開 Device control。這些 URL 會忽略上述 3 個選項。它們一律不是唯讀模式。除了 Device control URL 之外,其他 URL 都需要管理員帳戶。
在信任 Device control 前,請先確認它可以存取哪些內容。Assist 預設會公開新的實體,其中也包括 covers。Home Assistant 文件有明確說明:「Covers 包括車庫門和大門,因此 Home Assistant 也會自動公開這些項目。」locks、alarm panels 和 scripts 不會自動公開。請開啟 Assist 公開設定,移除任何您不希望聊天視窗開啟的實體。
使用專用帳號,而不是 owner
在 Claude 中選取 Connect 時,您會在瀏覽器中登入 Home Assistant。Claude 取得的存取權限,取決於您登入時使用的帳號。若您以 owner 登入,Claude 就會以 owner 的身分操作,擁有 owner 的所有權限。
在 Home Assistant 中建立一個獨立的 person,為其設定專用登入資訊,且只將此帳號用於 Claude。日後若要撤銷 Claude 的存取權限,只要刪除該帳號,不會影響您自己的登入資訊。接著選擇以下其中一種設定。
範圍狹窄:Claude 控制少數裝置。 將此帳號保留為一般使用者,不要設為 administrator。在主要 URL 選項中,關閉 Expose all AI tools,只選取 Device control,並關閉 Require an administrator account。如此一來,Claude 只能存取已公開給語音助理使用的 entity。若 Claude 只應回報狀態,也請開啟 Read-only。您也可以改用 /api/mcp/assist,此選項不需要 administrator。不過,該 URL 會忽略 Read-only 設定。
範圍廣泛:Claude 讀取日誌與歷史記錄。 Home Assistant 工具組一律需要 administrator 帳號。將專用帳號設為 administrator,但與 owner 分開,並開啟 Read-only。如此一來,Claude 可以讀取 entity、日誌與歷史記錄,但不會公開可變更設定的工具。
在 Connect 步驟中,確認您登入時使用的是哪個帳號。使用無痕瀏覽視窗執行此步驟,可降低誤用 owner 工作階段的風險。
不要將用戶端中的核准提示視為防護措施。在 connector 流程中,Home Assistant 文件指出,Claude 在呼叫任何工具前會要求許可。Claude Code 的行為不同。從 v2.1.283 起,auto mode 是互動式 terminal 與 VS Code 工作階段的起始權限模式,而 auto mode 不會在每個動作前要求確認。無論用戶端如何決定,Home Assistant 本身仍會強制套用帳號權限與 Read-only 設定。
Claude 的雲端應如何連線至 Home Assistant?
本節其餘內容是本指南根據各服務文件整理出的威脅模型。這些供應商都未在文件中說明其路徑無法防護哪些情況,因此請將本節視為分析,而不是供應商聲明。
以下每條路徑都有一個共同點:任何能連線至 URL 的人,都能到達 Home Assistant 的登入頁面。因此,請先設定登入防護。在 Settings > System > Network 的 HTTP server 區段中,開啟 Enable IP banning。接著設定 Login attempts before ban。此欄位接受 1 到 1000,且只有在關閉 Unlimited login attempts 時才會顯示。若使用任何 proxy 或 tunnel,也請開啟 Trust X-Forwarded-For,並將 proxy 的位址加入 Trusted proxies。Home Assistant 文件警告:「若未設定這些選項,來自 reverse proxy 的請求會遭到封鎖。」在 Home Assistant 2026.8 之前,這些設定位於 http: 的 configuration.yaml 區塊中。
Nabu Casa remote UI (Home Assistant Link)
Nabu Casa 的服務目前稱為 Home Assistant Link(原名 Home Assistant Cloud)。2026 年 11 月 15 日,其定價頁面列出的費用為每月 $6.50 USD 或每年 $65.00 USD,未含稅。頁面也列出 31 天免費試用,且不需要信用卡。Remote access 是列出的其中一項功能。
它會公開的內容:完整的 Home Assistant web interface 與登入頁面,位於公開的 HTTPS 位址。它不涵蓋的內容:Claude 所使用帳戶的弱密碼,或從其他地方洩漏的 token。本指南撰寫期間,Nabu Casa 的支援網站無法載入。請閱讀其官方文件,了解其 relay 能看見及無法看見的內容。
Tailscale Funnel
Funnel 會將來自公開網際網路的流量路由至本機服務,Tailscale 表示所有方案都可使用此功能。它需要 Tailscale v1.38.3 或更新版本、MagicDNS、tailnet 的有效 HTTPS 憑證,以及 tailnet policy file 中的 funnel node attribute。它只能監聽 443、8443 和 10000 埠。Claude 需要使用 443 埠。若這些需求對你而言不熟悉,Tailscale 是什麼以及 tailnet 如何運作會加以說明。在執行 Home Assistant 的機器上執行:
sudo tailscale funnel 8123Tailscale 會輸出公開的 https://<machine>.<tailnet>.ts.net 位址,該位址會 proxy 至 http://127.0.0.1:8123。在 connector URL 中使用此主機名稱。由於每個請求現在都來自本機 Tailscale proxy,請將 127.0.0.1 加入 Home Assistant 的 Trusted proxies。按下 Ctrl+C 前,該命令會以前景模式執行。
它會公開的內容:完整的 Home Assistant 埠,供網際網路上的任何人存取。Funnel 的訪客不需要 Tailscale,因此你的私人 tailnet 不會為他們增加額外屏障。Funnel 流量也有無法設定的頻寬限制。
Cloudflare Tunnel
Cloudflare Tunnel 使用僅向外的連線。網路內的 cloudflared daemon 會向外連線至 Cloudflare,因此你不必開啟入站埠,家中也不需要公開 IP。
它會公開的內容:你發布的主機名稱,供整個網際網路存取,除非你在前方加入規則。要求使用者先登入 Cloudflare 的規則,必須允許 Anthropic 發布的 IP ranges 通過。Claude 的雲端無法填寫登入頁面,因此其 MCP requests 會在 Cloudflare 停止。請將 cloudflared 用來連線至 Home Assistant 的位址加入 Trusted proxies。
A reverse proxy on a VPS
使用此路徑時,你可以控制面向網際網路的伺服器。具備公開 IP 的小型 VPS(virtual private server)會執行 reverse proxy,並透過 tailnet 等 private link 連線至家中的 Home Assistant。家中的任何服務都不會對網際網路開放。你也可以限制哪些來源能連線至 proxy。
Anthropic 會發布其用於對外請求的 IP addresses,「例如對外部伺服器進行 MCP tool calls 時」。2026 年 11 月 15 日,該頁面列出兩個以 CIDR 表示的 outbound IPv4 ranges,且沒有 outbound IPv6 range。請在設定當天,從 Anthropic 的 IP address 頁面複製目前的 ranges。該頁面也列出已不再使用的舊位址,因此只取目前的 outbound ones。
在 VPS 上安裝 Caddy後,/etc/caddy/Caddyfile 可以丟棄所有不是來自這些 ranges 的連線:
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 頁面上的 outbound IPv4 ranges,將 203.0.113.25 替換為你自己的 public IP,並將 100.101.102.103 替換為 Home Assistant 在 tailnet 上的位址。清單中必須包含你自己的 IP,因為 Connect 步驟會在瀏覽器中開啟 Home Assistant 的登入頁面。該請求來自你,而不是 Anthropic。若 Connect 停留在永遠無法載入的頁面上,表示清單中缺少你的位址。Caddy 預設會設定 X-Forwarded-For、X-Forwarded-Proto 和 X-Forwarded-Host headers,也會 proxy WebSocket connections。只要主機名稱的 DNS record 指向 VPS,Caddy 也會為該主機名稱取得 TLS(transport layer security)certificate。
caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddycaddy validate 應在無錯誤的情況下完成。從不在清單中的位址執行時,curl -I https://ha.example.com/ 應完全收不到 HTTP response,因為 abort 會關閉連線。最後,將 VPS 的 tailnet 位址加入 Home Assistant 的 Trusted proxies。
它無法防護的內容:所有 Claude 使用者都共用 Anthropic 的 IP ranges。allowlist 可以排除隨機掃描器。任何得知你的 URL 並將其加入自己 connector 的人,仍可到達你的登入頁面,因此帳戶密碼與 IP banning 仍然重要。此外,你現在還必須維護並修補一台 VPS。
Which path to pick
Nabu Casa 的設定最簡單,也不需要自行管理伺服器。Funnel 和 Cloudflare Tunnel 都不必在家中開啟埠,但兩者都會將完整登入頁面放在公開網際網路上。VPS proxy 需要最多設定工作,但暴露範圍最小,因為只有 Anthropic 的 ranges 和你自己的位址能開啟連線。無論選擇哪條路徑,專用帳戶與 Read-only 開關提供的防護,都比路徑本身更重要。
在 Claude 中新增連接器
- 在 claude.ai 中開啟 Customize > Connectors,選取 + Add > Add custom connector。在 Claude Desktop 中,Home Assistant 文件指定依序開啟 Settings > Connectors,再選取 Add > Add custom connector。
- 將名稱設為
Home Assistant,並貼上完整 URL,例如https://ha.example.com/api/mcp。 - 將 Authentication 設為 Sign in now,將 OAuth client 設為 Use Claude's published identity,然後選取 Add。
- 在新連接器的頁面中選取 Connect,並使用專用帳號登入 Home Assistant。
若使用 Team 或 Enterprise 方案,Owner 會在 Organization settings > Connectors 下新增連接器。之後,每位成員都可在 Customize > Connectors 中找到該連接器並選取 Connect,因此每位成員都必須完成 Home Assistant 登入程序。
之所以選擇已發布的 identity,是因為這符合 Home Assistant 處理 OAuth 的方式。Home Assistant 以 PKCE(proof key for code exchange)實作 OAuth 2.0。它支援 OAuth Client ID Metadata Documents,因此會自動設定 client ID 與 callback URL。Home Assistant 不使用 client secret。它也不支援 RFC 7591 Dynamic Client Registration,文件指出,嚴格要求此功能的 client「cannot register automatically」。對於其他 MCP client,文件指出 Client ID 必須是 client application 的 base URL,「never your Home Assistant instance URL」。
將 Home Assistant 加入 Claude Code
claude mcp add --transport http home-assistant https://ha.example.com/api/mcp
claude mcp login home-assistantclaude mcp login 會從 shell 執行伺服器的 OAuth 流程。透過遠端伺服器的 SSH 工作階段時,也可使用 --no-browser。預設情況下,claude mcp add 使用 local scope,將伺服器限制在此電腦上的目前專案。加入 --scope user 後,所有專案都能使用該伺服器。在 Claude Code 中,/mcp 會顯示伺服器是否已連線。如果 Claude Code 執行於 Linux,且尚未完成設定,請參閱在 Linux 桌面與 CLI 上執行 Claude的安裝說明。
長效 token 或 OAuth:較早的指南指的是哪一種?
較早的指南會要求你建立長效 access token。這在指南撰寫時是正確的。並沒有任何單一的 Home Assistant 版本將機制從 token 切換為 OAuth。這項變更是分階段發生的:
- 第一版 MCP Server 文件撰寫於 2025.2,內容指出:「目前,我們可以使用 Long-lived access token 控制 API 的存取權。」
- 自 31 March 2025 起,文件改為說明透過 IndieAuth 使用 OAuth。文件也指出,部分 MCP client 支援 access token,但不支援 OAuth。
- 採用 S256 方法的 PKCE 首次出現在 Home Assistant 原始碼的 tag 2026.10.0 中。在 2026.9.0 的原始碼中尚未包含這項功能。
- 目前的 MCP Server 頁面未提及長效 token。
如果指南要求將 token 貼入請求標頭,表示那是較早期的設定方式。請改用上方目前的 OAuth 步驟。
何時選擇社群 ha-mcp server?
ha-mcp 是採用 MIT 授權的獨立專案。其 v9.2.0 標籤中的 README 列出 87 個工具。預設分支上的 README 已經列出 86 個工具,因此數量會因建置版本而變動。如果您需要比內建工具集更大型、專為特定用途設計的工具清單,且能接受不同的認證模式,請選擇 ha-mcp。
v9.2.0 建議使用 HA-MCP integration 安裝。它會在 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。此 integration 會使用管理員權限執行,其文件也建議使用專用的 HA-MCP 帳號。此專案也提供 Docker image、PyPI package 及 Home Assistant app(add-on);其 README 另說明可使用本機 stdio 模式,但僅供測試。
鎖定穩定版本
截至 15 November 2026,最新的穩定版本是 v9.2.0,於 11 November 發布。開發版本(.devN)會在每次推送至 master 時發布,而在本次檢查前的 24 小時內出現了 5 個 dev tag。專案本身的建議很明確:「Dev releases(.devN)可能包含錯誤。正式環境請使用穩定版本。」請安裝 v9.2.0 版本,不要使用 .devN build。Docker image 的 :latest 與 :stable tag 會追蹤穩定版本,不會追蹤 dev build。如果使用 uvx 執行,README 中的指令會以 @latest 結尾。請將其替換為 @9.2.0,因為 uv 的 @ 語法需要指定確切版本。PyPI package 需要 Python 3.13 或 3.14。
private_ URL 就是密碼
內建 server 會要求 Claude 登入。主要的 ha-mcp 模式則不會。在您的網路中,其位址類似 http://<ha-ip>:9584/private_<random>。從遠端存取時,則是類似 https://<your-ha-domain>/api/webhook/<webhook-id> 的 webhook URL。專案文件指出「路徑就是憑證」,並要求您「將 URL 視同密碼:不要分享,也不要貼到可能留下日誌的位置。」任何取得完整 URL 的人都能連入您的 MCP server,中間不會有登入頁面。
這會改變威脅模型。將 URL 貼到共用聊天中,或讓它留在 proxy log 裡,都會提供完整存取權。如果 URL 外洩,請產生新的 webhook ID 來取代它。在 endpoint 結尾加入 /readonly,即可取得隱藏 write tools 並封鎖 write calls 的連線。遠端存取可透過 Nabu Casa remote UI,或您已在使用的 reverse proxy。若使用 Cloudflare Tunnel,README 會指向其 Setup Wizard。
ha-mcp 也提供標示為 beta 的 OAuth 模式。它仍會要求每位使用者將 Home Assistant long-lived access token 貼入同意表單。這與內建 server 的登入機制不同。
為什麼 connector 無法登入?
登入頁面完全沒有出現,或 Claude 表示無法連線至伺服器。 Anthropic 的雲端服務無法連線至該 URL。請從家用網路以外的網路測試 443 埠,若有使用 allowlist,也請檢查相關設定。
透過 proxy 時登入因 OAuth 錯誤而失敗。 Home Assistant 文件指出,原因是反向代理標頭(X-Forwarded-Host、X-Forwarded-Proto)遺失或不相符。文件也補充:「符合規範的 OAuth 用戶端會拒絕這項中繼資料。」Home Assistant 建立的 URL 必須與 Claude 使用的確切主機名稱和 scheme 相符。請修正 proxy 標頭和 Trusted proxies 設定。
對 /register 的請求傳回 404。 用戶端嘗試使用 Dynamic Client Registration,但 Home Assistant 不支援此功能。在 Claude 中,將 OAuth client 設為 Use Claude's published identity。
已知的開放問題。 2026 年 11 月 15 日,issue #183050 回報 claude.ai connector 在 Core 2026.11.0 上對 /api/mcp 連線失敗。該問題仍未關閉,並標記為需要更多資訊,尚未確認修正方式。請先測試 connector,再將其用於正式依賴的工作流程。
FAQ
Claude Desktop 會從我的電腦連線到 Home Assistant 嗎?
自訂連接器不會。Anthropic 與 Home Assistant 都表示,包括 Claude Desktop 在內,Claude 會從 Anthropic 的雲端連線。因此,Home Assistant 必須在 443 埠提供公開的 HTTPS 位址。例外是 claude_desktop_config.json 中的本機伺服器,以及會從您自己的電腦連線的 Claude Code。
Claude 可以透過 Home Assistant MCP 開啟我的車庫門嗎?
可以,前提是帳戶與工具集允許此操作。Assist 預設會公開新的 cover,而 cover 包含車庫門與閘門,因此 Device control 工具集通常可以存取這些裝置。Home Assistant 工具集可以執行任何操作。如果不希望 Claude 操作這些裝置,請從 Assist 公開項目中移除相關實體,或為主要 URL 開啟 Read-only。
我仍需要 Home Assistant MCP 伺服器的長效存取權杖嗎?
內建伺服器不需要。目前文件使用採用 PKCE 的 OAuth 2.0,未提及長效權杖。2025.2 的第一版文件則使用權杖。社群版 ha-mcp 伺服器不同:其 beta OAuth 模式仍要求您貼上長效權杖。
連接器多次失敗後,我無法登入 Home Assistant。發生了什麼事?
IP banning 封鎖了登入失敗的位址。Home Assistant 文件指出,最可能的原因是 OAuth 設定錯誤,例如 client ID 或 Home Assistant URL 錯誤。請在 Home Assistant 設定目錄中開啟 ip_bans.yaml,移除遭封鎖位址的項目,然後重新啟動 Home Assistant。再次嘗試前,請先修正連接器設定。