【2026 最新】HA-MCP 教學：Claude 怎麼接 Home Assistant？六步學會唯讀驗證與自動化還原

你在 Home Assistant 看得到列印機影像，Claude 卻說讀不到；接著你又想請它改自動化，心裡開始擔心：它究竟看到了什麼，又能動到哪裡？這篇 HA-MCP 教學，就從這兩個問題開始。

本文寫給已經有 Home Assistant、第一次接觸 MCP 的讀者。先用白話分清實體、工具與憑證，再在獨立測試安裝裡，用兩個虛擬開關走完「查詢、拒絕、修改、還原」。你不必先會寫程式，但需要能管理自己的 Home Assistant，並逐項核對畫面。

以下依 2026 年 11 月 13 日查閱的專案文件、v9.2.0 原始碼與 Home Assistant 文件整理；本次沒有連線住宅設備，操作段是可自行驗收的練習流程。

先說結論：可控接線＝讀對實體＋限制入口＋驗證還原

把 HA-MCP 想成替 AI 接上一張智慧家庭工作台。AI 負責理解要求，工作台提供查詢與修改工具；接上工作台，還要確認每支工具適用哪種實體，以及伺服器是否真的拒絕越界操作。

• 第一輪只讀：先核對實體 ID、原始狀態與工具參數。
• 第二輪驗限制：確認寫入工具被隱藏，且測試寫入沒有生效。
• 第三輪只改一條測試自動化：先存原稿與備份，再讀回、觸發、還原。

一、HA-MCP 教學先認五個零件

• Home Assistant：「家裡的總控台」。它連接裝置、保存狀態並執行自動化。
• Entity（實體）：「有地址的控制項」。同一台裝置可以提供多個實體。input_boolean.mcp_lab_trigger 的句點前是 domain（類型），後面是個別名稱。
• MCP：「工作台的接線規格」。它讓客戶端取得工具描述並提出呼叫；工具名稱、輸入與回傳仍由各伺服器定義。
• HA-MCP：「提供這組工具的社群專案」。本文指 homeassistant-ai/ha-mcp；Home Assistant 本身另有 Model Context Protocol 整合，設定入口與工具集合要分開看。
• Claude Code：「操作工作台的客戶端」。它透過 MCP 使用工具。連線成功只能證明接得上；某次查詢或變更有沒有正確完成，還要看工具回傳與 Home Assistant 狀態。

憑證則像總控台的鑰匙。專用帳號能讓身分與撤銷比較清楚，但若帳號仍是管理員，它就仍有廣泛權限。若想先理解工具與執行控制的關係，可接著讀 Agent Harness 是什麼。

若你還在選擇程式開發客戶端，可先讀 Claude Code 與 Codex 的工作方式比較；本文的接線範例固定用 Claude Code，讓每一步的設定與工具回應容易追蹤。

二、先搭練習場，再依版本選安裝入口

第 1 步：「出錯會動到什麼？」先準備兩個虛擬開關

優先使用沒有真實裝置、沒有正式自動化的獨立測試安裝。依 Input boolean 官方步驟，到 Settings → Devices & services → Helpers → Create helper → Toggle 建立兩個 helper（輔助控制項）。把名稱分別設成 MCP Lab Trigger 與 MCP Lab Result，並記下畫面實際分配的實體 ID。

下文用 input_boolean.mcp_lab_trigger 與 input_boolean.mcp_lab_result 示範。若實際 ID 多了尾碼，就全部換成你的值；不要猜名稱會自動對上。確認它們沒有接到其他動作，先把兩個開關都設為 off，記下 Home Assistant、HA-MCP 與客戶端版本。

第 2 步：「哪個安裝方法才對？」只保留一個伺服器

截至查閱日，專案 最新穩定版為 v9.2.0。目前文件推薦把完整伺服器放進 Home Assistant 的整合內；安裝前先看 整合式伺服器需求與設定：

• Home Assistant 2026.11 以上：在 Settings → Marketplace 搜尋 HA-MCP。
• Home Assistant 2026.8–2026.10：在 HACS 搜尋 HA-MCP 並下載。整合式伺服器的安裝門檻為 2026.8.0。
• 安裝後重新啟動 Home Assistant，到 Settings → Devices & Services → Add Integration，搜尋 HA-MCP，選 HA-MCP Server。已有 app／add-on、Docker 或 stdio 安裝者，先核對現有版本與入口，避免同時跑兩個互不相同的伺服器。

帳號選專供測試 HA-MCP 的管理員帳號。此路徑的設定可輸入該帳號登入資料，讓整合建立 token，或貼入管理員長效 token。本文首跑選本機客戶端與區域網路：開啟所需的 Network access: Local network，遠端存取保持關閉；不必為練習另開網際網路連入。

啟動後到該項目的 Configure 複製連線 URL。舊版教學可能叫你從日誌找 URL，現行整合文件指定的是 Configure。官方 Setup Wizard 可依客戶端產生設定；選擇你已經在跑的安裝方式。

三、HA-MCP 教學首跑：先查對實體，再驗唯讀

第 3 步：「Claude 看的是哪個地址？」核對查詢與 domain

先在伺服器的 Tools 設定開啟 Read Only Mode，依安裝方式重新啟動或重新載入使設定生效，再重連客戶端。另把 HTTP 連線 URL 末端加上 /readonly；例如一般入口是 http://HA_IP:9584/private_YOUR_SECRET，唯讀入口就是其後接 /readonly。這是格式示意，IP、連接埠與秘密路徑都要以你的 Configure 畫面為準。

在已安裝 Claude Code 的本機終端機，可依 Anthropic MCP 文件 加入 HTTP 伺服器。下列第一行從終端機讀入你貼上的完整唯讀 URL，避免把真實 URL 直接寫進指令歷史；CLI 的輸出和本機設定仍可能包含該 URL，請留在私人環境。

read -r HA_MCP_READONLY_URL
claude mcp add --transport http ha-lab-readonly --scope local "$HA_MCP_READONLY_URL"
unset HA_MCP_READONLY_URL

啟動 Claude Code，用 /mcp 檢查連線。local 是 Claude Code 的設定範圍，和 Home Assistant 帳號的 Local access only 是兩件事。切換端點或伺服器設定後，重新連線並重查工具清單；舊對話可能還保留先前的工具描述。

請只查詢 MCP Lab 的兩個 helper。先用 ha_search 找出實體，再用 ha_get_state 核對。
逐一回報 entity_id、domain、原始 state；找不到就停止，不要建立或改名。
不要查詢影像、居家位置或其他私人裝置，也不要執行任何變更。

把結果與 Home Assistant 的實體畫面比對。若出現 unknown、unavailable 或相似名稱，先排錯；AI 說「找到了」不能代替 ID 與狀態一致。

2026 年 11 月 10 日的 Issue #3038 就是一個例子：回報者在 HA-MCP 9.1.2 的 app 安裝裡，用 ha_get_camera_image 讀列印機的 image.*，收到 domain 驗證錯誤。這是該使用者的回報，不是本文的測試結果。

再核對 v9.2.0 的 camera 工具實作：它在呼叫相機代理前，明確檢查 domain 必須是 camera，其他類型會被拒絕。因此這版的該工具不能直接收 image.*。畫面看得到圖片，並不保證這個工具能讀；不要把 ID 的前綴硬改成 camera，也不要為了取得圖片而改用有寫檔副作用的流程。遇到此情況，留下版本、實體類型與錯誤碼，回到工具 schema（參數規格）和後續發布紀錄核對。

第 4 步：「真的拒絕寫入嗎？」留下伺服器證據

依 唯讀限制的實作，伺服器同時做工具清單過濾與呼叫時檢查，寫入會被擋下並回報 READ_ONLY_MODE。不過，工具被隱藏時，客戶端可能根本不送出呼叫；這與伺服器收到呼叫後拒絕，是兩種不同證據。

• 記錄重連後的工具清單：一般寫入工具應被隱藏；有些混合工具仍保留讀取用途。
• 只在獨立測試安裝，嘗試把 Result helper 設為 on。若工具不存在或客戶端拒絕，記成「客戶端未送出」，不要宣稱已取得伺服器拒絕證據。
• 若測試客戶端能送出已知寫入呼叫，保留其結構化拒絕結果，再於 Home Assistant 確認 Result 仍為 off。若真的變成 on，停止寫入練習，重新查端點、全域設定與連線版本。

唯讀 URL 是這條連線的模式，不是另一把權限更小的鑰匙。專案端點說明 明列同一憑證仍可連一般入口；全域 Read Only Mode 開啟時，兩個入口都受限制。只在 Prompt 寫「不要改東西」，也沒有替伺服器建立限制。

四、只改一條自動化：先留原稿，再核准與還原

第 5 步：「怎麼把變更縮到能看懂？」從兩個 helper 開始

先由你在 Home Assistant 的 Settings → Automations & scenes 建立一條全新的測試自動化。依 官方編輯器操作 選 Create automation，再切到 Edit in YAML，貼入下面的範例。保存後記下實際的 automation.* ID，並把這份原始 YAML 存在本機私人檔案。

alias: MCP Lab Only
description: "Lab baseline"
triggers:
  - trigger: state
    entity_id: input_boolean.mcp_lab_trigger
    from: "off"
    to: "on"
conditions: []
actions:
  - action: input_boolean.turn_on
    target:
      entity_id: input_boolean.mcp_lab_result
mode: single

這條規則的意思是：Trigger 從 off 變 on，Result 就變 on。它只指向你剛建的兩個 helper。先讓兩者回到 off，再由你手動切換 Trigger，確認 Result 變 on，並打開自動化的 Trace（執行軌跡）。這一輪是你的基線；觀察不符就停在這裡。

接著關閉這條自動化，兩個 helper 回到 off。確認 HA-MCP 的自動備份已開啟，並在設定面板查得到這條規則的變更前備份；也可依當前工具描述，用 ha_manage_backup 的 scope="edits"、action="create" 建立單項快照，再用 list／view 核對。備份沒有成功，就保留本機原稿，先解決備份問題再繼續。

現在才進入一般連線：保留唯讀客戶端，另建一個只用於這次修改的本機連線，指向 Configure 的一般入口。由你關閉全域唯讀設定，完成必要的重新載入與重連。先讓 Claude 讀取 工具要求的 skill guide，再送出這段要求：

先用 ha_config_get_automation 讀取我指定的測試 automation ID，保留完整 config 與 config_hash。
只提出一個差異：把唯一 action 從 input_boolean.turn_on 改成 input_boolean.turn_off。
目標仍只能是 MCP Lab Result；保留原本 id、觸發條件、名稱及其他欄位。
先列出修改前後，等我明確核准才寫入；不得自動執行動作、重啟或修改其他規則。

你看過差異並核准後，要求它重新讀取目前設定，用新取得的 config_hash 與完整 config 更新同一個 ID。這可避免拿過期原稿蓋掉期間的變更。若 hash 不符，重新讀取與比較；不要移除保護硬寫。

寫入後，再用 ha_config_get_automation 讀回，確認只改了那個 action。由你把 Result 設為 on、Trigger 設為 off，啟用測試規則，再把 Trigger 切為 on。過關觀察是 Result 變 off，而且 Trace 指向這條規則。只按 Run actions 會跳過觸發與條件，不能用來驗證完整流程；官方自動化排錯說明 也把「動作能跑」與「觸發有發生」分開處理。

第 6 步：「真的回得去嗎？」復原設定，也復原測試狀態

先停用測試規則。依 單項備份工具說明，用 scope="edits" 列出並查看修改前的備份，核對規則 ID、時間與內容後，才對該 backup_name 執行 restore。這裡要的是單條規則復原；scope="snapshot" 是 Home Assistant 系統備份復原，會重新啟動 HA，不適合拿來做這個練習。

讀回後，與本機原稿逐欄比較，確認 action 回到 turn_on。設定復原與 helper 當前狀態分開驗：先把兩個 helper 設為 off，再啟用規則、切 Trigger 為 on，確認 Result 回到 on。若備份復原失敗，保持規則停用，透過 HA 編輯器貼回原稿，再做相同讀回與觸發核對。

收尾時先停用或刪除你剛建立的測試規則，再清理兩個 helper；一般寫入連線移除，伺服器回到唯讀。若不再使用整合，就停用伺服器項目。想完成撤權，還要依實際驗證模式處理：秘密 URL 需輪替連線秘密；登入模式要撤銷對應 token；自行貼入的長效 token 要到該帳號的 Security 刪除。移除客戶端設定，不等於在 Home Assistant 撤銷憑證。

撤銷後，用舊連線重新連線並嘗試讀取測試狀態，記錄失敗；同時確認新的唯讀連線仍符合預期。整合的安全與 token 說明 將關閉入口、輪替秘密與撤銷帳號憑證分別處理。你的驗收紀錄也應分成這三欄。

五、常見問題：八個先講答案的判斷

1. 一定要先買智慧家庭裝置嗎？

不用。練習使用既有測試安裝與兩個 Toggle helper；它們是軟體狀態。開始前先確認沒有其他自動化訂閱這些 helper。

2. HA-MCP 就是 Home Assistant 內建 MCP 嗎？

不是同一個專案。本文工具來自 homeassistant-ai/ha-mcp；內建整合有自己的設定與工具集合，不能混用兩套教學的 URL。

3. 唯讀連線能讓圖片自動變得可讀嗎？

不能解決 domain 不符。v9.2.0 的 ha_get_camera_image 檢查 camera 類型；唯讀限制與工具支援的輸入類型要分開驗。

4. 畫面沒有寫入工具，就證明伺服器有擋下呼叫？

還不夠。那證明清單過濾；要聲稱呼叫被拒絕，需有伺服器實際回傳的拒絕證據。

5. 專用管理員帳號等於最小權限嗎？

不等於。它改善身分區分與撤銷，但仍是管理員。此練習依靠隔離測試安裝、伺服器唯讀限制與單條變更來縮小影響。

6. 備份還原後，helper 會一起回到測試前嗎？

要分開確認。這裡復原的是那條自動化設定；本流程要求另外重設兩個 helper，再重新觸發驗證。

7. 只按 Run actions 成功，可以交差嗎？

不可以用它代表完整觸發測試。請真的做一次 off 到 on 的狀態轉換，並核對 Trace。

8. 第一次最值得完成哪一步？

先完成唯讀查詢，把兩個 helper 的 ID、domain 與原始 state 核對一致，再留下端點與版本紀錄。這已能判斷接線是否接對。

給新手的三個重點

• 先讀對地址：友善名稱、entity ID 與 domain 分開核對，圖片在畫面出現也要查工具規格。
• 再驗限制：清單隱藏、呼叫拒絕與狀態未變是三種證據；唯讀端點和憑證撤權也不同。
• 最後驗還原：原稿、備份、config_hash、讀回與 Trace，讓一條變更有明確的前後狀態。