homeassistant-ai/ha-mcp 是什麼？

ha-mcp 是社群維護的 MCP 伺服器，讓 Claude 等 AI 助理以自然語言操作 Home Assistant。本文拆解它的架構、安裝路徑與潛在陷阱。

homeassistant-ai/ha-mcp 可以商用嗎？

可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。

homeassistant-ai/ha-mcp 還在維護嗎？

有在維護。儲存庫在最近一天內有新的提交。

homeassistant-ai/ha-mcp 是用什麼程式語言寫的？

主要是 Python（依據 GitHub 的語言統計）。

ha-mcp Home Assistant MCP 伺服器解析：架構、安裝與限制

秒懂

它是什麼？: ha-mcp 是社群維護的 MCP 伺服器，讓 Claude 等 AI 助理以自然語言操作 Home Assistant。本文拆解它的架構、安裝路徑與潛在陷阱。
適合誰用？: ha-mcp 適合已經熟悉 Home Assistant 且想讓 AI 助理直接控制裝置的使用者，尤其是 Claude Desktop 或 ChatGPT 的重度玩家。不適合從未碰過 MCP 的新手，因為多種安裝方式容易混淆，而且開啟檔案編輯工具會大幅擴張攻擊面。
可以商用嗎？: 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
還在維護嗎？: 有在維護。儲存庫在最近一天內有新的提交。
用什麼語言寫的？: 主要是 Python（依據 GitHub 的語言統計）。

以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。

開源專案深度解析

Hysen Labs 編輯部 · 2026年9月10日 · homeassistant-ai/ha-mcp

這專案解決什麼問題，誰該用

Home Assistant 的介面與自動化引擎很強，但對一般使用者來說，要記住每個實體 ID、服務名稱與 YAML 語法並不容易。ha-mcp 把這些操作包成 Model Context Protocol（MCP）工具，讓 AI 助理用自然語言就能查狀態、執行服務、甚至管理自動化。它鎖定的對象是已經有 Home Assistant 基礎、同時想讓 Claude 或 ChatGPT 直接插手家電的人。不是給剛入門的智慧家庭新手用的，因為你需要先懂 Home Assistant 的實體與服務概念，才能判斷 AI 給的指令是否合理。

三種執行方式，架構上的根本差異

ha-mcp 的 README 強調 in-process 的 Home Assistant Custom Component 是最佳解，透過 HACS 安裝後，伺服器直接跑在 Home Assistant 程序內，不需要另外管理 access token。這是與其他 MCP 伺服器最大的不同，多數同類專案是獨立程序，透過 WebSocket 或 REST API 連到 Home Assistant。in-process 意味著工具可以直接呼叫 Home Assistant 的內部 API，不需要繞過網路層，延遲較低，但代價是你只能跑在 Home Assistant 所在的機器上。另外兩種方式是 Home Assistant app（add-on）與 Docker/PyPI 的 stdio 模式，前者適合 HA OS 或 Supervised 安裝，後者適合想自己控制程序生命週期的進階使用者。README 明確警告：同一時間只能選一種安裝方式，混用會造成衝突，這點很容易被忽略。

從 HACS 到連接 URL：實際安裝步驟

安裝路徑以 HACS 為主流。先在 HACS 的 Integrations 選單中，透過自訂儲存庫加入 https://github.com/homeassistant-ai/ha-mcp-integration，類別選 Integration，下載後重啟 Home Assistant。接著到 Settings 的 Devices & Services 搜尋 HA-MCP Custom Component，選擇 HA-MCP Server 並提交，伺服器就啟動了。關鍵步驟是從該整合的 Configure 畫面複製連接 URL，格式是 https://<你的網域>/api/webhook/<webhook-id>，或區域網路直接用 http://<ha-ip>:9584/private_<random>。把這個 URL 貼到 Claude Desktop 或 ChatGPT 的 MCP 設定即可。若不想開放遠端，可以在選項中關閉 Remote access via webhook，這樣就不會註冊 webhook，只保留本機連接埠。

工具數量與檔案編輯的雙面刃

README 標榜 87 個工具，涵蓋狀態查詢、服務執行、自動化管理等，但這些工具並非全部預設開啟。檔案與 YAML 編輯工具是 opt-in，預設關閉，需要另外安裝 HA-MCP File & YAML Tools 這個第二入口。這是刻意的安全設計，因為讓 AI 直接改 YAML 設定檔等於給它一把鏟子，可能挖掉整個自動化架構。如果你只是要控制燈泡或查溫度，不需要開這些工具，但若想讓 AI 幫你寫自動化，就得承擔風險。README 也提到 v7.3.0 把 ha_config_set_yaml 移到 beta，暗示這類工具仍在實驗階段，行為可能變動。

認證機制：secret URL 與 ha_auth 的取捨

預設的認證方式是把 webhook URL 當作密碼，誰拿到 URL 誰就能控制你的家。這對家庭使用者來說很方便，但 URL 一旦外流，等於交出鑰匙。ha-mcp 提供另一個選項：把 Webhook authentication 設為 ha_auth，要求連線者用 Home Assistant 帳號登入，而不是只靠 URL。這個選項值得認真考慮，尤其是你會把 URL 貼進雲端 AI 服務時。不過 README 沒有說明 ha_auth 是否支援細緻的權限控制，例如限制只能控制特定裝置，這點在官方文件釋出前無法確認。若你的 Home Assistant 暴露在網際網路，強烈建議開啟 ha_auth，並搭配 Nabu Casa 或反向代理的既有防護。

版本更新節奏與維護成本

從 release 列表看，ha-mcp 的開發頻率很高，v8.4.3.dev2608 到 dev2605 之間只隔了幾個小時，這代表專案非常活躍，但也意味著 API 可能快速變動。README 中提到的 breaking change 就是例子，v7.3.0 把 ha_config_set_yaml 移到 beta，這對依賴舊版行為的腳本會造成破壞。採用者必須追蹤 release notes，否則 AI 工具突然失效時會一頭霧水。好消息是專案以 MIT 授權釋出，你可以自由修改，但這也表示沒有商業支援，出問題只能靠 GitHub issues 或自行除錯。若你的 Home Assistant 是長期穩定派，建議鎖定特定版本，不要追 dev 版。

替代方案：官方整合與其他 MCP 伺服器

Home Assistant 本身有官方的 Assist 管道，可以透過對話式 AI 控制裝置，但它著重在語音與日常指令，不允許 AI 直接編輯 YAML 或管理自動化。ha-mcp 的差異在於工具面更廣，涵蓋系統管理層級的操作。另一個常見替代是直接撰寫 REST API 呼叫給 AI，但這需要你為每個操作手動定義 API 結構，無法像 ha-mcp 那樣開箱即用。若你只需要基本控制，官方 Assist 較安全，因為它受限於 Home Assistant 的意圖系統，不會任意執行服務。但若你要讓 AI 處理複雜的自動化除錯或批次狀態變更，ha-mcp 的工具深度是官方方案做不到的。

編輯結論

ha-mcp 適合已經熟悉 Home Assistant 且想讓 AI 助理直接控制裝置的使用者，尤其是 Claude Desktop 或 ChatGPT 的重度玩家。不適合從未碰過 MCP 的新手，因為多種安裝方式容易混淆，而且開啟檔案編輯工具會大幅擴張攻擊面。採用前先確認你的 Home Assistant 版本是否支援 HACS 自訂整合，並決定要走 in-process 元件還是獨立 add-on，兩者不可並存。若只要查詢狀態而不需要執行服務，可以考慮官方 Assist 管道的對話式控制，但若需要自動化編輯與跨裝置批次操作，ha-mcp 的 87 個工具是目前最直接的選擇。

官方來源

社群筆記