Home Assistant MCP Server

🚀 家庭助手 MCP 服務器

家庭助手 MCP 服務器是一個與 Home Assistant 集成的 Model Context Protocol (MCP) 服務器，它能讓大語言模型（LLM）控制和查詢您的智能家居系統，為智能家居的交互提供了更智能、便捷的方式。

🚀 快速開始

家庭助手 MCP 服務器可讓您使用自然語言與智能家居交互，還支持多種客戶端。以下是快速上手的步驟：

1. 完成服務器的安裝。
2. 進行必要的配置。
3. 啟動服務器並開始使用。

✨ 主要特性

• 自然語言交互：支持使用自然語言查詢和控制家庭助手實體，讓操作更加便捷。
• 廣泛兼容性：支持任何 MCP 兼容客戶端，如 Claude Desktop。
• 豐富工具支持：提供狀態管理、服務調用、歷史記錄等實用工具。
• 安全身份驗證：使用家庭助手長期訪問令牌進行安全身份驗證。
• 多種傳輸選項：有標準 I/O（用於本地進程）和 SSE（用於遠程客戶端）兩種傳輸選項。
• 演示模式：當沒有家庭助手時，可使用模擬數據進行測試和演示。

📦 安裝指南

您可以選擇使用 bun 全局安裝，也可以從源代碼進行安裝：

# 使用 bun 全局安裝
bun install -g home-assistant-mcp-server

# 或從源代碼安裝
git clone https://github.com/oleander/home-assistant-mcp-server.git
cd home-assistant-mcp-server
bun install
bun run build
bun link

📚 詳細文檔

配置

在當前目錄中創建一個 .env 文件，包含以下變量：

# 必填配置
HASS_URL=http://your-home-assistant:8123  # 家庭助手實例的 URL
HASS_TOKEN=your_long_lived_access_token   # 長期使用的訪問令牌

# 可選配置
PORT=3000                # HTTP 服務器端口（默認：3000）
HASS_MOCK=false          # 啟用 mock 數據模式以在沒有家庭助手時進行測試和演示（默認：false）

環境變量

獲取長期訪問令牌的步驟如下：

1. 登錄到您的家庭助手實例。
2. 點擊底部左側的個人資料。
3. 滾動到底部“長壽命訪問令牌”。
4. 創建一個具有描述性名稱的新令牌。
5. 複製令牌值（您將不會再看到它）。

使用

作為獨立服務器運行

# 標準模式（需要運行中的家庭助手實例）
home-assistant-mcp-server                # 使用 HTTP/SSE 運輸啟動
home-assistant-mcp-server --stdio       # 使用標準 I/O 啟動

# 演示模式
npm start -- --mock

集成到 Claude Desktop

將 MCP 服務器配置為環境變量：

export MCP_SERVER_URL=http://localhost:5005
export MCP_SERVER_INSECURE=true

然後運行 Claude。

安全注意事項

⚠️ 重要提示

• 避免在不安全的網絡中暴露令牌。
• 考慮使用具有有限權限的令牌。
• 定期更新令牌以增強安全性。

📄 許可證

此項目在 MIT License 下許可 - 有關詳細信息，請參閱 LICENSE 文件。