/ 目錄 / 演練場 / Home Assistant MCP
● 社群 homeassistant-ai 🔑 需要你的金鑰

Home Assistant MCP

作者 homeassistant-ai · homeassistant-ai/ha-mcp

用說話控制你的家。87 個工具涵蓋裝置控制、自動化、儀表板、能源、歷史紀錄——Claude 成為你的 Home Assistant 超級使用者。

ha-mcp 將 Home Assistant 的 REST 與 WebSocket API 封裝為 MCP 工具。除了開關燈光,它還能撰寫自動化、編輯儀表板、查詢歷史統計、管理 HACS 附加元件,並探索實體登錄——讓 Claude 既能診斷又能重新塑造你的智慧家庭。

為什麼要用

核心特性

即時演示

實際使用效果

ha-mcp.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "ha-mcp",
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "ha-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "ha-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add ha-mcp -- uvx ha-mcp

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: Home Assistant MCP

不需記住實體 ID 即可控制裝置

👤 任何已設定好 Home Assistant 的使用者 ⏱ ~5 min beginner

何時使用: 你知道自己想要什麼(「把廚房調暗到 30%」),但不知道確切的 entity_id。

前置條件
  • Home Assistant 長效存取 Token — 個人資料 → 安全性 → 建立 Token;儲存為 HA_TOKEN 環境變數
  • 已設定 HA_URL — 設定 HA_URL=http://homeassistant.local:8123(或你的 URL)
步驟
  1. 尋找實體
    Use ha-mcp. Find entities matching 'kitchen light'. Show entity_id, area, and current state.✓ 已複製
    → 1–3 個候選實體及其目前狀態
  2. 套用變更
    Set kitchen ceiling lights to 30% brightness, warm white.✓ 已複製
    → 服務呼叫成功;狀態已確認

結果: 依意圖控制裝置,無需死背 ID。

注意事項
  • 多個實體符合條件——切換到錯誤的實體 — 批次操作前務必確認 entity_id 清單;使用區域篩選

從白話文規格描述建立複雜自動化

👤 不想手寫 YAML 的 HA 使用者 ⏱ ~15 min intermediate

何時使用: 你想要「如果我離開家、日落後、貓咪餵食器空了,就傳通知給我」——但不想寫 YAML。

步驟
  1. 描述意圖
    Use ha-mcp. List my person tracker, sun, and cat feeder entities so we can wire an automation.✓ 已複製
    → 相關實體及其狀態結構
  2. 生成 YAML
    Create automation 'cat-feeder-sundown-alert' with that logic. Don't deploy yet — show me the YAML.✓ 已複製
    → 對話中顯示有效的 HA 自動化 YAML
  3. 部署並追蹤
    Deploy it. Then trigger it manually and show the trace so I can verify the conditions fired.✓ 已複製
    → 自動化出現在 UI 中;追蹤顯示預期分支已觸發

結果: 自動化正常運作,無需手動編輯 /config/automations.yaml。

注意事項
  • 自動化已部署但從未觸發——實體名稱有錯字 — 使用追蹤工具;確認 entity_id 完全匹配

利用歷史與統計資料調查能源用量異常

👤 擁有 HA 能源儀表板的智慧家居用戶 ⏱ ~25 min intermediate

何時使用: 電費帳單暴增,你想知道是什麼改變了。

步驟
  1. 拉取用量總計
    Use ha-mcp. Compare total kWh per circuit for last 30 days vs the prior 30. Flag deltas >20%.✓ 已複製
    → 各迴路用量表格,標示出異常差異
  2. 深入最嚴重的迴路
    For the worst-offending circuit, plot hourly usage for the last 7 days and identify the new pattern.✓ 已複製
    → 每小時用量圖表及異常模式說明
  3. 找出罪魁禍首裝置
    Which entity on that circuit changed behavior? Cross-reference automations that touch it.✓ 已複製
    → 找出具體裝置及相關自動化

結果: 得到明確的答案,例如「電動車充電器啟用了新排程」,而非模糊的猜測。

注意事項
  • 統計資料的品質取決於感測器覆蓋範圍 — 承認盲點;建議需要新增監測的位置

設置「出遊模式」——一次性控制燈光、門鎖、百葉窗與通知

👤 即將出門旅遊的人 ⏱ ~30 min intermediate

何時使用: 一小時後要出發,想設定模擬在家的燈光效果及外出行為。

步驟
  1. 清點受影響的實體
    Use ha-mcp. List lights in living areas, all door locks, all blinds. Note which are HA-controllable.✓ 已複製
    → 依類別分類的實體清單及可控制標記
  2. 建立腳本
    Create a script 'vacation_mode_on' that arms locks, randomizes evening lights 18:30–22:30, sets blinds to 50%, and pauses cleaning automations.✓ 已複製
    → 腳本已存入 HA;手動執行成功
  3. 新增觸發器
    Bind it to an input_boolean 'vacation_mode' so I can toggle from the dashboard.✓ 已複製
    → 儀表板上有切換開關;撥動後執行腳本

結果: 一鍵啟動出遊模式;出門前儀表板已設定妥當。

注意事項
  • 家裡有人時自動上鎖 — 加入人員在家偵測;有人在家時絕不上鎖

組合

與其他 MCP 搭配,撬動十倍槓桿

ha-mcp + filesystem

將 automations.yaml 和 scripts.yaml 備份至 git

Export all automations and scripts via ha-mcp, write to ./ha-config/, commit.✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
search_entities query: str, area?, domain? 幾乎每個流程的第一步——尋找 entity_id 1 次 HA API 呼叫
call_service domain, service, target, data 套用任何裝置或場景變更 1 次 API 呼叫
create_automation yaml_or_object 以程式方式建立自動化 1 次 API 呼叫
get_history entity_id, start, end 拉取狀態歷史以進行分析 1 次 API 呼叫
get_statistics statistic_id, period(5min|hour|day|month) 長期彙總資料(能源、氣候) 1 次 API 呼叫
trace_automation automation_id, run_id? 偵錯自動化為何觸發或未觸發 1 次 API 呼叫

成本與限制

運行它的成本

API 配額
無硬性配額——REST API 為本機呼叫
每次呼叫 Token 數
不定;若不篩選,實體登錄可能非常龐大
費用
免費(開放原始碼)
提示
務必使用帶篩選條件的 search_entities——完整登錄傾倒會消耗大量 token

安全

權限、密鑰、影響範圍

最小權限: 長效存取 Token(完整 HA 範圍)
憑證儲存: HA_TOKEN 環境變數
資料出站: 僅連至你的 HA 實例 URL——理想情況下保持在區域網路內
切勿授予: 將 HA token 提供給任何你不信任的雲端 LLM——這會控制實體存取(門鎖、車庫)

故障排查

常見錯誤與修復

無法連線至 HA

確認 HA_URL 可從 MCP 執行位置存取;若在反向代理後方,請檢查 trusted_proxies 設定

驗證: curl $HA_URL/api/ -H 'Authorization: Bearer $HA_TOKEN'
401 Unauthorized

Token 已過期或被撤銷——在個人資料中生成新的長效 token

服務呼叫回傳 400

服務簽名不符——使用開發者工具面板確認 schema,然後重試

自動化已部署但未觸發

使用 trace_automation 查看哪個條件未達成;常見原因:entity_id 錯字或日出日落條件時區錯誤

替代方案

Home Assistant MCP 對比其他方案

替代方案何時用它替代權衡
Home Assistant 原生語音助理(Piper/Whisper)你想要語音控制,且不希望雲端 LLM 介入自然語言靈活性較低;設定較繁瑣
ha-mcp-server(舊版/分支版本)你的分支版本有此版本沒有的功能功能範圍較小;此版本有 87 個工具且持續維護

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills