Enhanced Homeassistant MCP

🚀 增強版Home Assistant MCP

增強版Home Assistant MCP是一個全面的MCP（模型上下文協議）服務器，它與Home Assistant深度集成，使AI助手能夠與智能家居設備、自動化系統和系統管理進行交互，為智能家居控制帶來更智能、便捷的體驗。

🚀 快速開始

使用NPX快速啟動

無需安裝！ 直接使用npx運行：

# 設置你的Home Assistant憑證
export HOMEASSISTANT_URL="http://your-ha-ip:8123"
export HOMEASSISTANT_TOKEN="your-long-lived-access-token"

# 啟動服務器
npx @thelord/enhanced-homeassistant-mcp

📖 完整的NPX使用指南 →

🚧 Smithery部署狀態：目前正在優化工具加載，以防止Smithery工具掃描期間出現超時問題。詳情請參閱 TIMEOUT_RESOLUTION.md。

✨ 主要特性

📊 基本操作

• ✅ API狀態驗證
• 📱 實體狀態管理
• 🔄 帶高級參數的服務調用
• 📝 實體發現和列表展示
• 🛠️ 配置信息獲取

🤖 自動化與控制

• 📜 自動化管理（啟用/禁用/觸發）
• 🎬 場景激活
• 📜 腳本執行
• 🔘 輸入布爾值控制
• 📅 定時自動化洞察

📊 歷史記錄與監控

• 📈 實體歷史跟蹤
• 📝 日誌條目記錄
• ⚠️ 錯誤日誌監控
• 📡 系統事件監測
• 🔍 配置驗證

🏠 設備控制

• 💡 燈光：亮度、顏色、溫度控制
• 🌡️ 氣候設備：溫度、HVAC模式、預設控制
• 📺 媒體播放器：播放/暫停、音量、媒體選擇控制
• 🏠 遮陽簾：打開/關閉、位置控制
• 📢 通知：多服務消息發送
• 🔍 設備發現：按類型/域過濾

⚙️ 系統管理

• 📊 系統信息和健康狀態
• 🏷️ 模板渲染（Jinja2）
• 🏠 區域和設備管理
• 🔌 集成監控
• 🔄 系統重啟功能
• 📱 管理器和插件管理
• 🔍 實體搜索和發現

📦 安裝指南

前提條件

• Node.js 18+
• 具有API訪問權限的Home Assistant實例
• Home Assistant的長期訪問令牌

安裝步驟

# 克隆倉庫
git clone https://github.com/gilberth/enhanced-homeassistant-mcp.git
cd enhanced-homeassistant-mcp

# 安裝依賴
npm install

# 複製環境模板
cp .env.example .env

配置

編輯 .env 文件，填入你的Home Assistant詳細信息：

HOME_ASSISTANT_URL=http://homeassistant.local:8123
HOME_ASSISTANT_TOKEN=your_long_lived_access_token_here
DEBUG=false
REQUEST_TIMEOUT=10000

獲取訪問令牌

1. 在瀏覽器中打開Home Assistant
2. 轉到你的個人資料（點擊側邊欄中的用戶名）
3. 向下滾動到“長期訪問令牌”
4. 點擊“創建令牌”
5. 給令牌命名並複製生成的令牌

運行服務器

選項1：NPX（推薦 - 無需安裝）

# 快速啟動
npx @thelord/enhanced-homeassistant-mcp

# 帶選項啟動
npx @thelord/enhanced-homeassistant-mcp --debug start
npx @thelord/enhanced-homeassistant-mcp inspect
npx @thelord/enhanced-homeassistant-mcp health

選項2：本地安裝

# 開發模式
npm run dev

# 生產模式
npm run build
npm start

# 使用MCP檢查器（用於測試）
npm run inspector

🐳 Docker部署（推薦）

使用Docker進行簡單安全的部署：

# 構建鏡像
docker build -t enhanced-homeassistant-mcp .

# 運行容器
docker run -d \
  --name homeassistant-mcp \
  --restart unless-stopped \
  -e HOME_ASSISTANT_URL="http://your-hass-ip:8123" \
  -e HOME_ASSISTANT_TOKEN="your_long_lived_token" \
  enhanced-homeassistant-mcp

📖 完整的Docker指南：請參閱 DOCKER.md 獲取詳細說明。

☁️ Smithery部署（雲端）

要使用通過Smithery部署在雲端的服務器：

1. 訪問：Smithery.ai
2. 搜索：@gilberth/enhanced-homeassistant-mcp
3. 配置你的實例：
   • Home Assistant URL
   • 長期訪問令牌
   • 可選選項（調試、超時）

// 使用Smithery SDK
import { createSmitheryUrl } from "@smithery/sdk";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const config = {
  homeAssistantToken: "your_token",
  homeAssistantUrl: "http://your-hass-ip:8123",
};

const serverUrl = createSmitheryUrl(
  "https://server.smithery.ai/@gilberth/enhanced-homeassistant-mcp",
  { config, apiKey: "your-smithery-api-key" }
);

🎯 Smithery的優勢：無需基礎設施配置、自動擴展和全球訪問。

🛠️ 可用工具

基本工具

自動化工具

歷史記錄工具

設備控制工具

系統工具

💻 使用示例

基礎用法

// 獲取燈光狀態
const lightState = await homeassistant_get_entity_state({
  entity_id: "light.living_room",
});

// 打開燈光並設置亮度和顏色
const result = await homeassistant_control_lights({
  entity_id: "light.living_room",
  action: "turn_on",
  brightness_pct: 75,
  color_name: "warm_white",
});

高級用法

自動化管理

// 列出所有自動化
const automations = await homeassistant_list_automations();

// 啟用一個自動化
const enabled = await homeassistant_toggle_automation({
  entity_id: "automation.morning_routine",
  action: "turn_on",
});

// 激活一個場景
const scene = await homeassistant_activate_scene({
  entity_id: "scene.movie_time",
});

氣候控制

// 設置恆溫器溫度
const climate = await homeassistant_control_climate({
  entity_id: "climate.living_room",
  temperature: 22,
  hvac_mode: "heat",
});

系統信息

// 獲取系統概述
const systemInfo = await homeassistant_system_info();

// 搜索實體
const searchResults = await homeassistant_search_entities({
  search: "temperature",
  domain: "sensor",
});

🎮 客戶端示例

在 目錄中提供了可用的客戶端示例：

📁 可用示例

• simple-client.js - 基本連接和工具使用
• smithery-client.js - 全功能演示
• secure-client.js - 基於環境的安全配置

🚀 快速開始示例

cd examples
npm install
cp .env.example .env
# 編輯.env文件，填入你的憑證
npm run secure

🔗 與Smithery一起使用：這些示例可直接與部署在 Smithery.ai 上的服務器配合使用。 📖 詳細指南：請參閱 獲取完整的設置說明。

🔧 技術細節

項目結構

src/
├── index.ts                    # 主服務器文件
├── utils/
│   └── api.ts                  # API實用工具
└── tools/
    └── homeassistant/
        ├── basic.ts            # 基本HA操作
        ├── automation.ts       # 自動化工具
        ├── history.ts          # 歷史記錄和監控
        ├── devices.ts          # 設備控制
        └── system.ts           # 系統管理

添加新工具

1. 在適當的工具文件中創建一個新函數
2. 使用 server.tool() 向服務器註冊它
3. 遵循現有的錯誤處理和響應格式化模式
4. 在README中添加文檔說明

測試

# 使用檢查器進行交互式測試
npm run inspector

# 測試特定端點
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "http://localhost:8123/api/states"

🚑 故障排除

常見問題

連接失敗

• 驗證 HOME_ASSISTANT_URL 是否正確且可訪問
• 檢查Home Assistant是否正在運行
• 確保沒有防火牆阻止連接

認證失敗

• 驗證你的長期訪問令牌是否正確
• 檢查令牌是否未過期或被撤銷
• 確保令牌具有必要的權限

實體未找到

• 使用 homeassistant_list_all_entities 查找正確的實體ID
• 檢查實體是否存在並在Home Assistant中啟用
• 驗證正確的域前綴（例如，light., sensor.）

服務調用失敗

• 使用 homeassistant_list_services 驗證服務是否可用
• 檢查服務參數是否適合你的設備
• 某些服務需要特定的實體類型或狀態

調試模式

在 .env 中啟用調試日誌：

DEBUG=true

🤝 貢獻

1. 分叉倉庫
2. 創建一個功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 打開一個拉取請求

開發指南

• 遵循現有的代碼風格和模式
• 添加適當的TypeScript類型
• 為所有API調用包含錯誤處理
• 為新功能更新文檔
• 使用真實的Home Assistant實例進行測試

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• Home Assistant - 出色的智能家居平臺
• Model Context Protocol - 協議規範
• TypeScript - 編程語言和工具

📞 支持

如果遇到問題或有疑問：

1. 查看 故障排除部分
2. 搜索現有的 GitHub問題
3. 創建一個新問題，包含：
   • Home Assistant版本
   • MCP服務器日誌
   • 重現步驟
   • 預期與實際行為對比

為Home Assistant社區用心打造 ❤️