Home Assistant Integration

🚀 家庭助手 MCP

家庭助手 MCP 是一個模型上下文協議（MCP）集成，藉助人工智能助手實現對家庭助手設備的控制，為智能家居控制帶來便捷體驗。

🚀 快速開始

家庭助手 MCP 允許人工智能助手控制您的家庭助手設備。它提供了以下實用工具：

1. 在您的家庭助手實例中搜索實體。
2. 控制設備（打開/關閉）。
3. 控制燈光顏色和亮度。

📦 安裝指南

先決條件

• Python 3.11 或更高版本。
• 運行中的家庭助手實例，可通過 API 訪問。
• 家庭助手長期訪問令牌。

安裝步驟

1. 克隆此倉庫。
2. 設置 Python 環境：

cd home-assistant
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
pip install -U pip
pip install uv
uv pip install -e .

📚 詳細文檔

配置

獲取家庭助手長期訪問令牌

1. 轉到您的家庭助手實例。
2. 導航到您的配置文件（點擊側邊欄中的用戶名）。
3. 滾動到底部“長期訪問令牌”。
4. 創建一個帶有描述性名稱的新令牌，例如“MCP 集成”。
5. 複製令牌（您只會在創建時看到它）。

在 Cursor AI 中設置

將以下配置添加到您的 MCP 配置中：

{
  "mcpServers": {
    "home_assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/home-assistant-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "HOME_ASSISTANT_TOKEN": "your_home_assistant_token_here"
      },
      "inheritEnv": true
    }
  }
}

替換：

• /path/to/your/home-assistant 為您實際的家庭助手目錄路徑。
• your_home_assistant_token_here 您的長期家庭助手訪問令牌。

家庭助手 URL 配置

默認情況下，MCP 嘗試連接到位於 http://homeassistant.local:8123 的家庭助手。 如果您的家庭助手位於不同的 URL，可以在 app/config.py 中修改 HA_URL 變量。

使用方法

配置完成後，您可以使用 Cursor AI 控制您的家庭助手設備：

• 搜索設備：例如，“查找我的客廳燈”。
• 控制設備：例如，“打開廚房燈”。
• 控制燈光顏色：例如，“將我的客廳燈設置為紅色”。
• 調整亮度：例如，“將我的餐廳燈設置為藍色，50% 亮度”。

燈光控制功能

MCP 現在支持高級燈光控制功能：

1. 顏色控制：設置兼容燈的任意 RGB 顏色。
   • 使用 RGB 值（每個組件 0 - 255）指定顏色。
   • 示例：set_device_color("light.living_room", 255, 0, 0) 設置為紅色。
2. 亮度控制：調整燈光亮度。
   • 可選的亮度參數（0 - 255）。
   • 可與顏色更改結合使用。
   • 示例：set_device_color("light.dining_room", 0, 0, 255, brightness=128) 設置為中等亮度藍色。

故障排除

• 如果您遇到身份驗證錯誤，請檢查令牌是否正確且未過期。
• 確保您的家庭助手實例可以訪問配置的 URL。
• 對於顏色控制問題：
  • 驗證燈實體是否支持 RGB 顏色控制。
  • 檢查燈是否已打開，然後再嘗試更改顏色。

未來功能

動態實體暴露

當前實現需要通過自然語言搜索實體然後控制設備的兩步過程：

1. 使用自然語言搜索實體。
2. 使用其特定 entity_id 控制實體。

計劃中的增強是創建一種更動態的方式將實體暴露給 MCP，以便直接控制它們。 例如：

• 對於燈：“客廳燈”。
• 對於智能插座：“廚房插座”。

這將允許 MCP 直接與設備交互，而無需先搜索其 ID。