Homeassistant MCP

一個連接Home Assistant與LLM的MCP協議服務器，實現智能家居的自然語言控制與監控

家庭自動化與物聯網開發者工具 #智能家居 #語言控制 #自動化管理 #即時監控 .TypeScript

評分 : 3.5分

下載量 : 9.6K

更新時間 : 2025-04-29

打開站點

什麼是MCP服務器？

MCP服務器是一個強大的工具，用於通過自然語言控制和監控您的智能家居設備。它使您能夠輕鬆管理Home Assistant中的所有設備和服務。

如何使用MCP服務器？

只需幾步即可開始使用MCP服務器。首先確保安裝並配置好Home Assistant，然後運行MCP服務器並連接到您的設備。

適用場景

MCP服務器非常適合希望用自然語言控制智能家居設備的人士，例如通過語音助手發送指令。

主要功能

設備控制

支持控制各種類型的設備，如燈光、恆溫器、窗簾、開關等。

即時更新

通過Server-Sent Events (SSE) 實現即時狀態更新。

自動化管理

創建、修改和管理Home Assistant的自動化規則。

狀態監控

即時跟蹤和查詢設備的狀態。

安全保護

採用基於令牌的身份驗證和速率限制機制。

優勢

易於集成和使用

支持多種設備類型

提供即時反饋

侷限性

需要穩定的網絡連接

高級功能可能需要一定的技術知識

如何使用

安裝MCP服務器

克隆項目代碼並在本地運行。

配置環境變量

編輯.env文件以設置Home Assistant的相關信息。

啟動服務器

使用Docker Compose啟動MCP服務器。

使用案例

案例1：控制燈光

向MCP服務器發送命令以打開或關閉指定房間的燈光。

案例2：管理自動化

創建一個新的自動化規則，當檢測到運動時自動打開燈光。

常見問題

如何獲取Home Assistant的長壽命訪問令牌？

如果遇到連接問題怎麼辦？

是否支持多平臺客戶端？

🚀 模型上下文

本項目提供了 home-assistant-model-context 模塊，用於與 Home Assistant 進行交互，實現實體、樓層和區域訪問、設備控制等功能，方便開發者進行相關開發。

🚀 快速開始

你可以按照以下步驟快速開始使用本項目：

安裝項目依賴。
參考使用示例進行開發。
依據開發指南進行項目的運行、構建等操作。

📦 安裝指南

使用以下命令安裝 home-assistant-model-context：

npm install home-assistant-model-context

💻 使用示例

基礎用法

const { ModelContext } = require('home-assistant-model-context');

// 初始化模型上下文
async function initializeModel() {
  const model = new ModelContext({
    host: 'localhost',
    port: 8123,
    tokenPath: '/config/secrets.yaml'
  });

  // 獲取當前狀態
  await model.initialize();
  const state = await model.getState('light.living_room');
  console.log('燈的狀態:', state.state);
}

// 執行初始化
initializeModel().catch(console.error);

📚 詳細文檔

運行命令

# 開發模式（帶熱重載）
npm run dev

# 構建項目
npm run build

# 生產模式
npm run start

# 運行測試
npx jest --config=jest.config.cjs

# 代碼格式化
npm run lint

# 生成文檔
npm run doc:gen

配置文件

// config.json
{
  "host": "localhost",
  "port": 8123,
  "token": "your_api_key_here"
}

🔧 技術細節

故障排除

常見問題

Node.js 版本（toSorted is not a function）
- 解決方案： 更新到 Node.js 20.10.0+
```
nvm install 20.10.0
nvm use 20.10.0
```
連接問題
- 確保 Home Assistant 正在運行
- 檢查 HASS_HOST 是否可訪問
- 驗證令牌權限
設備管理問題
- 確保 Supervisor 訪問權限
- 檢查添加組件兼容性
- 驗證系統資源

項目狀態

✅ 已完成

實體、樓層和區域訪問
設備控制（燈、氣候、遮陽篷、開關、聯繫人）
添加件管理功能
HACS 集成包管理
先進的自動化配置
基本狀態管理
錯誤處理與驗證
Docker 容器化
Jest 測試框架
TypeScript 整合

🚧 進行中

WebSocket 實現以支持即時更新
增強安全特性
工具組織優化
性能優化
資源上下文整合
API 文檔生成
多平臺桌面整合
高級 macOS 整合
類型安全改進
測試覆蓋率擴展

項目貢獻

叉倉庫
創建功能分支
實現更改
添加新功能的測試
確保所有測試通過
提交拉取請求

資源鏈接

📄 許可證

MIT License

版權所有 (c) 2023, Author 姓名

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.