homeassistant-ai/ha-mcp

📚 什麼是 ha‑mcp？

ha‑mcp（Home Assistant 模型上下文協定伺服器）是一個非官方但功能完整的伺服器，讓大型語言模型助手（Claude、ChatGPT、Gemini 等）能與 Home Assistant 實例互動。它實作了 模型上下文協定（MCP），讓 AI 客戶端能：

查詢任何實體（燈光、感應器、攝影機等）的狀態。
控制設備，透過任何 Home Assistant 服務進行操作。
建立、編輯與除錯自動化、腳本、儀表板、助手、區域、群組、藍圖、HACS 插件、備份等。
讀取日誌、歷史記錄與自動化追蹤，協助 AI 排除問題。
切換安全功能（唯讀模式、工具級權限、自動編輯備份），確保您對 AI 可能變更的內容保持控制。

簡而言之，它將對話式 AI 變成一個功能完整的 Home Assistant 管理員，不僅能開關燈，更能建構與維護您的整個智慧家居設定。

🚀 如何執行？

ha‑mcp 可透過 四種方式 安裝，所有方式均提供一個 AI 客戶端可指向的單一 URL：

方法	執行位置	常見使用情境
HA‑MCP 自訂元件（推薦）	在 Home Assistant 內部作為自訂整合（透過 HACS 安裝）	適用於所有 Home Assistant 安裝類型（OS、Supervised、Container、Core）。無需額外權杖。
Home Assistant 應用 / 插件	作為 Home Assistant OS / Supervised 上的獨立「應用」執行	適合希望使用獨立程序但仍需內建 Webhook 實現遠端存取的使用者。
Docker / PyPI / uvx HTTP 伺服器	在 Home Assistant 外部（任意主機）執行	適用於無法執行插件的容器或核心安裝，或希望將伺服器部署在其他機器上的情況。
本地 stdio	直接在您的筆電/桌上型電腦上執行（不推薦用於生產環境）	快速示範或調試；存在已知傳輸問題。

所有方法都會產生一個秘密 Webhook URL（或直接本地埠），您需將其貼到 AI 客戶端的 MCP 設定中。

🔧 快速入門（自訂元件）

透過 HACS 新增整合 – 使用 README 中的徽章，或在 HACS 中新增倉儲 https://github.com/homeassistant-ai/ha-mcp-integration 為自訂倉儲。
重新啟動 Home Assistant。
在 設定 → 設備與服務 → 新增整合 中，搜尋 HA‑MCP 自訂元件，並新增 HA‑MCP 伺服器 項目。
伺服器啟動後，開啟其設定畫面；Webhook URL（例如 https://my‑ha.duckdns.org/api/webhook/abcd1234）會顯示，也會出現在 Home Assistant 日誌中。
將該 URL 貼到您的 AI 客戶端的 MCP 設定中 – 現在 AI 助手就能與 Home Assistant 通訊了。

該整合還新增了一個側邊欄面板，用於管理工具、功能開關、備份和主題，並支援啟用可選的 Webhook 認證（ha_auth）。

🛠️ AI 實際能做什麼？

ha‑mcp 提供了 87 個「工具」，依功能分組。README 中示範的一些常見操作包括：

類別	例子工具
控制	`ha_call_service`, `ha_bulk_control` – 開關設備、調節氣候等
自動化與腳本	`ha_config_get_automation`, `ha_config_set_automation`, `ha_config_get_script`, `ha_config_set_script` – 建立或修改自動化和腳本
儀表板 / UI	`ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_get_dashboard_screenshot` – 新增卡片、編輯 Lovelace 布局
檔案與 YAML (測試版)	`ha_read_file`, `ha_write_file`, `ha_config_get_yaml`, `ha_config_set_yaml` – 編輯原始設定檔
系統與維護	`ha_manage_backup`, `ha_manage_updates`, `ha_restart`, `ha_reload_core` – 備份/還原、更新 Home Assistant、重新啟動服務
除錯與監控	`ha_get_history`, `ha_get_logs`, `ha_get_automation_traces` – 取得日誌、查看實體歷史、除錯失敗的自動化
安全	`ha_manage_security_policy`, `唯讀模式切換` – 限制 AI 可變更的內容

當您要求 AI「建立一個日落時開啟門廊燈的自動化」時，它會在背後調用相應的 ha_config_set_automation 工具，撰寫 YAML 並重新載入設定。

🌐 遠端存取選項

內建 Webhook（由自訂元件使用） – 可與 Nabu Casa、Cloudflare Tunnel 或任何反向代理相容。
Webhook 代理應用 – 用於插件方法，透過現有的 Home Assistant Webhook 轉發 MCP 流量。
OpenAI Tunnel – 社群維護的隧道，讓 ChatGPT 風格的連接器能在不公開公開 URL 的情況下存取本地主機伺服器。
OIDC 認證 – 可選模式，透過外部身份提供者（Keycloak、Auth0 等）保護 Webhook。

📦 示範與設定精靈

該倉儲提供適用於 macOS、Linux 和 Windows 的一鍵式示範指令碼，可啟動一個暫時的 stdio 基礎伺服器，並連接到託管的示範 Home Assistant。執行指令碼後，您可以向 Claude、ChatGPT 或任何 MCP 相容客戶端提問：「你能看到我的 Home Assistant 嗎？」，以查看整合的實際效果。

還有一個基於網頁的設定精靈（https://homeassistant-ai.github.io/ha-mcp/setup/），可為所有支援的客戶端（Claude Code、Gemini CLI、ChatGPT、VS Code、Cursor 等）生成精確的客戶端特定設定。

🆚 與 Home Assistant 內建 MCP 伺服器的差異

功能	內建 MCP 伺服器	ha‑mcp
設備控制與狀態查詢	✅（僅對 Assist 暴露的實體）	✅（所有實體）
編輯自動化、腳本、場景	❌	✅
編輯儀表板 / Lovelace UI	❌	✅
訪問日誌、歷史記錄、自動化追蹤	❌	✅
管理助手、區域、群組、標籤	❌	✅
備份/還原、應用程式管理、HACS、裝置登錄表	❌	✅

對於簡單的語音風格指令，使用內建伺服器；當您希望 AI 能夠配置與維護整個 Home Assistant 設定時，請使用 ha‑mcp。

📚 更多學習資源

文件網站 – https://homeassistant-ai.github.io/ha-mcp/
設定精靈 – https://homeassistant-ai.github.io/ha-mcp/setup/
常見問題與故障排除 – https://homeassistant-ai.github.io/ha-mcp/faq/
GitHub 倉儲 – https://github.com/homeassistant-ai/ha-mcp（問題、貢獻指南、發行說明）

TL;DR

ha‑mcp 是一個真實、可投入生產環境的伺服器，它將大型語言模型助手與 Home Assistant 橋接，賦予 AI 對整個 Home Assistant 設定的完全讀寫存取權限。透過 HA‑MCP 自訂元件（最簡單路徑）安裝，取得生成的 Webhook URL，並將任何 MCP 相容的 AI 客戶端指向它——然後您就可以用自然語言讓 AI 建立自動化、編輯儀表板、除錯問題等。