Homeassistant MCP

🚀 家庭助理 Home Assistant 說明文檔

本說明文檔詳細介紹了家庭助理 Home Assistant 的配置、使用、集成等方面的內容，幫助你更好地使用該系統。

🚀 快速開始

本部分將引導你快速完成 Home Assistant 的基礎配置與啟動，讓你能夠儘快使用該系統。

✨ 主要特性

• 支持標準輸入輸出模式，方便與其他工具進行交互。
• 可與 Claude Desktop 集成，拓展功能。
• 具備完善的錯誤處理機制，便於排查問題。
• 提供日誌記錄和性能調優功能，保障系統穩定運行。

📦 安裝指南

MCP 服務器配置

配置文件示例

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "HASS_TOKEN": "your_home_assistant_token_here",
        "HASS_HOST": "http://your_home_assistant_host:8123"
      }
    }
  }
}

環境變量

• HASS_TOKEN：Home Assistant 的訪問令牌。
• HASS_HOST：Home Assistant 服務的 URL，格式為 http://IP:端口。

啟動腳本

方案一：使用 Node.js 直接運行

node index.js

方案二：使用 npm 腳包

1. 安裝 MCP 服務器：

npm install homeassistant-mcp

2. 啟動服務器：

npx homeassistant-mcp

使用 Home Assistant 的啟動腳本

將以下內容添加到 homeassistant.conf 文件中：

[HomeAssistantMCP]
command=node
args=index.js
environment=HASS_TOKEN="your_token_here",HASS_HOST="http://IP:port"

然後重啟 Home Assistant 服務。

💻 使用示例

啟動 MCP 服務器

npx homeassistant-mcp --stdio

發送請求示例

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getWeather",
  "params": {
    "location": "北京"
  }
}

接收響應示例

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "temperature": 25,
    "condition": "晴朗"
  }
}

📚 詳細文檔

標準輸入輸出模式（_stdio）

啟用標準輸入輸出模式

在 .env 文件中添加：

USE_STDIO_TRANSPORT=true

運行腳本

方案一：使用 Node.js 直接運行

node index.js --stdio

方案二：使用 npm 腳包

npx homeassistant-mcp --stdio

選項參數

• --debug：啟用調試模式。
• --rebuild：強制重新構建項目。
• --help：顯示幫助信息。

標準輸入輸出消息格式

請求格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tool-name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

響應格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    // 工具特定的結果數據
  }
}

錯誤響應格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32700,
    "message": "錯誤信息",
    "data": {} // 可選的錯誤細節
  }
}

通知格式（服務器到客戶端）

{
  "jsonrpc": "2.0",
  "method": "notification-type",
  "params": {
    // 通知數據
  }
}

支持的錯誤代碼

與 Claude Desktop 集成

配置步驟

修改配置文件

找到或創建以下路徑的配置文件：

• macOS：

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

• Linux：

nano ~/.config/Claude/claude_desktop_config.json

• Windows：

notepad %APPDATA%\Claude\claude_desktop_config.json

添加 MCP 服務器配置

在文件中添加或修改以下內容：

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "HASS_TOKEN": "your_token_here",
        "HASS_HOST": "http://IP:port"
      }
    }
  }
}

重啟服務

保存配置文件後，重啟 Claude Desktop 服務。

🔧 技術細節

錯誤處理

常見錯誤及解決方案

• 錯誤代碼 -32700：請求的 JSON 格式無效。請檢查請求數據是否符合 JSON 標準。
• 錯誤代碼 -32601：方法未找到。請確認調用的方法名稱正確且已註冊。
• 錯誤代碼 -32000：工具執行失敗。請檢查環境變量和依賴項是否配置正確。

高級功能

日誌記錄

啟用調試模式以獲取詳細日誌：

npx homeassistant-mcp --debug stdio

日誌文件通常位於項目目錄的 logs 文件夾中，具體位置取決於項目的配置。

性能調優

• 內存優化：使用 --max-old-space-size 參數限制 V8 引擎的最大內存佔用。

node --max-old-space-size=512 index.js --stdio

• 網絡性能：配置代理服務器或調整 HTTP 請求超時設置。

安全注意事項

• 訪問控制：確保 MCP 服務器僅允許來自受信任來源的連接。
• 令牌安全：存儲和傳輸 HASS_TOKEN 時，請確保使用安全協議（如 HTTPS）以防止未授權訪問。
• 日誌監控：定期審查日誌文件，發現並處理潛在的安全事件。

📄 許可證

文檔中未提及相關許可證信息。

更新日誌

版本 1.0.0 (2023 - 10 - 05)

• 新增標準輸入輸出模式支持。
• 優化錯誤處理機制。
• 改進與 Claude Desktop 的集成體驗。

版本 0.9.0 (2023 - 08 - 10)

• 初始版本發佈，提供基礎功能。

聯繫方式

如需反饋或技術支持，請訪問 官方文檔 或聯繫支持團隊。