Homeassistant MCP

一个连接Home Assistant与LLM的MCP协议服务器，实现智能家居的自然语言控制与监控

家庭自动化与物联网开发者工具 #智能家居 #语言控制 #自动化管理 #实时监控 .TypeScript

评分 : 3.5分

下载量 : 11.7K

更新时间 : 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.