Homeassistant Light MCP

🚀 Home Assistant Light MCP

Home Assistant Light MCP 是一個用於控制 Home Assistant 燈光並管理場景的模型上下文協議（MCP）服務器。它通過提供詳細的燈光顏色控制和場景管理功能，對官方 Home Assistant MCP 進行了補充。

🚀 快速開始

本項目是用於控制 Home Assistant 燈光和管理場景的 MCP 服務器。若你想使用它，可按照以下步驟進行操作：

1. 安裝項目（具體安裝方式見“📦 安裝指南”）。
2. 配置 MCP 客戶端（具體配置方式見“📦 安裝指南”）。
3. 參考“💻 使用示例”中的示例進行使用。

✨ 主要特性

• 展示燈光：查看所有燈光的詳細信息，包括狀態、亮度、RGB 顏色、色溫、顏色模式、支持的模式、可用效果（如顏色循環等）以及色溫範圍（最小/最大開爾文）。
• 調節燈光：控制燈光的開關、亮度、RGB 顏色、色溫以及效果。
• 創建場景：將當前燈光狀態保存為場景，有兩種模式可供選擇：
  • exclusive：激活時關閉其他燈光。
  • additive：僅影響場景中的燈光。
• 列出場景：查看所有已保存的場景。
• 激活場景：激活已保存的場景（支持宜家 Tradfri 燈具）。
• 更新場景：使用當前燈光狀態更新現有場景。
• 刪除場景：移除場景。
• 全滅燈：關閉所有燈光（可選擇排除部分燈光）。

📦 安裝指南

使用 npm 全局安裝

npm install -g ha-mcp-server

克隆倉庫並構建

git clone https://github.com/Koneisto/HomeAssistant-Light-MCP.git
cd HomeAssistant-Light-MCP
npm install
npm run build

配置 MCP 客戶端

Claude Desktop

編輯配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

選項 1：使用 npx（推薦，無需全局安裝）

{
  "mcpServers": {
    "ha-light-scenes": {
      "command": "npx",
      "args": ["-y", "ha-mcp-server"],
      "env": {
        "HA_URL": "http://your-home-assistant-ip:8123",
        "HA_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}

選項 2：全局安裝

npm install -g ha-mcp-server

{
  "mcpServers": {
    "ha-light-scenes": {
      "command": "ha-mcp-server",
      "env": {
        "HA_URL": "http://your-home-assistant-ip:8123",
        "HA_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}

其他 MCP 客戶端

相同的配置結構適用於任何兼容 MCP 的客戶端。

獲取 Home Assistant 令牌

1. 進入 Home Assistant → 個人資料（左下角）。
2. 滾動到“長期訪問令牌”。
3. 點擊“創建令牌”。
4. 複製令牌。

💻 使用示例

基礎用法

展示燈光

"Show me all the lights"（顯示所有燈光）

"What lights are on?"（哪些燈是亮著的？）

控制燈光

"Turn on living room light"（打開客廳燈）

"Set bedroom to 50% brightness"（將臥室燈光亮度設置為 50%）

"Make the kitchen light red"（將廚房燈設置為紅色）

"Set studio lights to warm white"（將工作室燈光設置為暖白色）

"Start colorloop on the hallway light"（開啟走廊燈的顏色循環效果）

創建場景

"Save this as Movie Night"（將此保存為“電影之夜”場景）

激活場景

"Activate Movie Night"（激活“電影之夜”場景）

更新場景

"Update Evening Lights with current settings"（用當前設置更新“晚間燈光”場景）

全滅燈

"Turn off all lights"（關閉所有燈光）

"Turn off all lights except the balcony"（關閉所有燈光，除了陽臺燈）

📚 詳細文檔

工具參考

燈光屬性

scene_show_lights 返回以下信息：

• state - 開關狀態
• brightness / brightness_pct - 亮度值（0 - 255 / 0 - 100%）
• rgb_color - [R, G, B] 值
• color_temp_kelvin - 色溫
• color_mode - 當前顏色模式（xy, color_temp, rgb, hs）
• supported_color_modes - 燈光支持的顏色模式
• effect - 激活的效果（如果有）
• effect_list - 可用的效果列表
• color_temp_range - 色溫範圍（最小/最大開爾文，如果支持）

場景模式

• Exclusive（獨佔模式）：關閉場景外的所有燈光，適用於特定房間的場景。
• Additive（疊加模式）：僅影響場景中的燈光，適用於重點照明。

本地備份與多實例支持

本 MCP 會對創建的場景進行本地備份：

• 自動備份：場景會保存到 ~/.config/ha-mcp-server/scenes-backup.json。
• 多實例感知：檢測其他 MCP 實例（或 HA UI）對場景的修改。
• 智能衝突解決：合併多個來源的更改。
• 恢復功能：如果 Home Assistant 丟失場景，可從本地備份中恢復。

診斷功能（scene_diagnose）

分析燈光和場景以識別問題：

• 測試燈光連接和響應時間。
• 檢測連接類型（Zigbee、WiFi、藍牙）。
• 查找包含空值或缺少燈光的場景。
• 比較 Home Assistant 狀態和本地備份。
• 報告未包含在獨佔場景中的新燈光。

示例："Run diagnostics on my lights"（對我的燈光進行診斷）

修復功能（scene_fix）

有四種操作可用於修復場景問題：

示例："Fix all my scenes"（修復我所有的場景）或 "Restore Evening Lights from backup"（從備份中恢復“晚間燈光”場景）

宜家 Tradfri 支持

宜家 Tradfri 燈具在 RGB 顏色模式和色溫（開爾文）模式之間切換時存在已知問題。燈泡在接受亮度或顏色值之前，需要時間處理模式更改。

注意：由於這些時序問題，Home Assistant 的原生場景與 Tradfri 燈具配合使用時不可靠。本 MCP 通過獨立管理場景並設置適當的延遲來提供解決方案。

本 MCP 會自動處理 Tradfri 燈具：

• 通過製造商名稱檢測 Tradfri 設備。
• 在模式切換和後續命令之間添加 500ms 延遲。
• 正確排序顏色/溫度更改和亮度調整。

如果沒有這些修復，Tradfri 燈具在切換模式時通常會忽略命令或產生不正確的顏色。

安全說明

數據本地保存

• 所有通信都直接在你的計算機和 Home Assistant 實例之間進行。
• 不會將數據發送到外部服務器或第三方。
• MCP 服務器通過標準輸入輸出在本地機器上運行（無開放網絡端口）。

無跟蹤

我們不會對你進行跟蹤。

令牌安全

• 你的 Home Assistant 令牌僅存儲在本地機器上。
• 使用環境變量避免將令牌存儲在文件中。
• 令牌僅發送到你自己的 Home Assistant 實例。
• 你可以隨時從 Home Assistant 設置中撤銷令牌。

服務器訪問權限

• 僅可訪問 Home Assistant 中的燈光和場景。
• 無法訪問其他 Home Assistant 實體（傳感器、鎖、攝像頭等）。
• 除了燈光控制和場景管理外，無法進行其他更改。

📄 許可證

本項目採用 MIT 許可證，你可以自由使用，建議保留原作者信息，但不做強制要求。

貢獻說明

如果你發現了 bug 或有新的想法，歡迎 提交問題 或發起拉取請求！

作者

Koneisto

Built by people with questionable priorities （由一群優先級存疑的人開發）