家庭助理的模型上下文协议服务器
服务器使用 MCP 协议与 LLM 应用程序共享对本地 Home Assistant 实例的访问权限。
您的 Home Assistant 实例与语言学习模型 (LLM) 之间的强大桥梁，通过模型上下文协议 (MCP) 实现对智能家居设备的自然语言控制和监控。该服务器提供全面的 API，用于管理您的整个 Home Assistant 生态系统，涵盖从设备控制到系统管理的各个方面。
特征
- 🎮设备控制：通过自然语言控制任何家庭助理设备
- 🔄实时更新：通过服务器发送事件（SSE）获取即时更新
- 🤖自动化管理：创建、更新和管理自动化
- 📊状态监控：跟踪和查询设备状态
- 🔐安全：基于令牌的身份验证和速率限制
- 📱移动就绪：可与任何支持 HTTP 的客户端配合使用
使用 SSE 进行实时更新
该服务器包含一个强大的服务器发送事件 (SSE) 系统，可从您的 Home Assistant 实例提供实时更新。这允许您：
- 🔄 获取任何设备的即时状态变化
- 📡 监控自动化触发器和执行
- 🎯 订阅特定域或实体
- 📊 跟踪服务调用和脚本执行
快速 SSE 示例
const eventSource = new EventSource(
'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Update received:', data);
};
有关 SSE 系统的完整文档，请参阅SSE_API.md 。
目录
主要特点
核心功能🎮
- 智能设备控制
- 💡灯光：亮度、色温、RGB 颜色
- 🌡️气候：温度、暖通空调模式、风扇模式、湿度
- 🚪封面：位置和倾斜控制
- 🔌开关：开/关控制
- 🚨传感器和接触器：状态监控
- 🎵媒体播放器：播放控制、音量、源选择
- 🌪️风扇：速度、摆动、方向
- 🔒锁：锁定/解锁控制
- 🧹吸尘器：启动、停止、返回基座
- 📹相机：运动检测、快照
系统管理🛠️
- 附加组件管理
- 浏览可用的附加组件
- 安装/卸载附加组件
- 启动/停止/重启附加组件
- 版本管理
- 配置访问
- 包裹管理（HACS）
- 与 Home Assistant Community Store 集成
- 多种封装类型支持：
- 自定义集成
- 前端主题
- Python 脚本
- AppDaemon 应用程序
- NetDaemon 应用程序
- 版本控制和更新
- 存储库管理
- 自动化管理
- 创建和编辑自动化
- 高级配置选项：
- 复制并修改现有的自动化
- 启用/禁用自动化规则
- 手动触发自动化
架构特点🏗️
- 智能组织
- 基于区域和楼层的设备分组
- 状态监控与查询
- 智能情境感知
- 历史数据访问
- 稳健的架构
- 全面的错误处理
- 状态验证
- 安全 API 集成
- TypeScript 类型安全
- 广泛的测试覆盖范围
先决条件
- Node.js 20.10.0 或更高版本
- NPM包管理器
- Docker Compose用于容器化
- 运行Home Assistant实例
- Home Assistant 长期访问令牌（如何获取令牌）
- 安装HACS以实现包裹管理功能
- 附加组件管理的主管访问权限
安装
通过 Smithery 安装
要通过Smithery自动为 Claude Desktop 安装 Home Assistant MCP 服务器：
npx -y @smithery/cli install @drejom/homeassistant-mcp --client claude
基本设置
# Clone the repository
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp
# Install dependencies
npm install
# Build the project
npm run build
Docker 设置（推荐）
该项目包括 Docker 支持，以便在不同平台之间轻松部署和保持一致的环境。
- 克隆存储库：
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp
- 配置环境：使用您的 Home Assistant 配置编辑
.env文件：# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
# Server Configuration
PORT=3000
NODE_ENV=production
DEBUG=false
- 使用 Docker Compose 构建并运行：
# Build and start the containers
docker compose up -d
# View logs
docker compose logs -f
# Stop the service
docker compose down
- **验证安装：**服务器现在应该在
http://localhost:3000上运行。您可以在http://localhost:3000/health检查健康端点。 - 更新应用程序：
# Pull the latest changes
git pull
# Rebuild and restart the containers
docker compose up -d --build
Docker 配置
Docker 设置包括：
- 多阶段构建以获得最佳图像尺寸
- 容器监控的健康检查
- 环境配置的卷安装
- 失败时自动重启容器
- 暴露 3000 端口用于 API 访问
Docker Compose 环境变量
所有环境变量都可以在.env文件中配置。支持以下变量：
HASS_HOST ：您的 Home Assistant 实例 URLHASS_TOKEN ：Home Assistant 的长期访问令牌HASS_SOCKET_URL ：家庭助理的 WebSocket URLPORT ：服务器端口（默认值：3000）NODE_ENV ：环境（生产/开发）DEBUG ：启用调试模式（true/false）
配置
环境变量
# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123 # Your Home Assistant instance URL
HASS_TOKEN=your_home_assistant_token # Long-lived access token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket # WebSocket URL
# Server Configuration
PORT=3000 # Server port (default: 3000)
NODE_ENV=production # Environment (production/development)
DEBUG=false # Enable debug mode
# Test Configuration
TEST_HASS_HOST=http://localhost:8123 # Test instance URL
TEST_HASS_TOKEN=test_token # Test token
配置文件
- 开发：将
.env.example复制到.env.development - 生产：将
.env.example复制到.env.production - 测试：将
.env.example复制到.env.test
添加到 Claude Desktop（或其他客户端）
要使用新的 Home Assistant MCP 服务器，您可以添加 Claude Desktop 作为客户端。将以下内容添加到配置中。请注意，这将在 Claude 中运行 MCP，并且不支持 Docker 方法。
{
"homeassistant": {
"command": "node",
"args": [<path/to/your/dist/folder>]
"env": {
NODE_ENV=development
HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
PORT=3000
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
LOG_LEVEL=debug
}
}
}
API 参考
设备控制
常见实体控制
{
"tool": "control",
"command": "turn_on", // or "turn_off", "toggle"
"entity_id": "light.living_room"
}
灯光控制
{
"tool": "control",
"command": "turn_on",
"entity_id": "light.living_room",
"brightness": 128,
"color_temp": 4000,
"rgb_color": [255, 0, 0]
}
附加组件管理
列出可用的附加组件
{
"tool": "addon",
"action": "list"
}
安装附加组件
{
"tool": "addon",
"action": "install",
"slug": "core_configurator",
"version": "5.6.0"
}
管理附加组件状态
{
"tool": "addon",
"action": "start", // or "stop", "restart"
"slug": "core_configurator"
}
包管理
列出 HACS 包
{
"tool": "package",
"action": "list",
"category": "integration" // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}
安装包
{
"tool": "package",
"action": "install",
"category": "integration",
"repository": "hacs/integration",
"version": "1.32.0"
}
自动化管理
创建自动化
{
"tool": "automation_config",
"action": "create",
"config": {
"alias": "Motion Light",
"description": "Turn on light when motion detected",
"mode": "single",
"trigger": [
{
"platform": "state",
"entity_id": "binary_sensor.motion",
"to": "on"
}
],
"action": [
{
"service": "light.turn_on",
"target": {
"entity_id": "light.living_room"
}
}
]
}
}
重复自动化
{
"tool": "automation_config",
"action": "duplicate",
"automation_id": "automation.motion_light"
}
核心功能
状态管理
GET /api/state
POST /api/state
管理系统的当前状态。
示例请求：
POST /api/state
{
"context": "living_room",
"state": {
"lights": "on",
"temperature": 22
}
}
上下文更新
使用新信息更新当前上下文。
示例请求：
POST /api/context
{
"user": "john",
"location": "kitchen",
"time": "morning",
"activity": "cooking"
}
行动端点
执行操作
使用给定的参数执行指定的动作。
示例请求：
POST /api/action
{
"action": "turn_on_lights",
"parameters": {
"room": "living_room",
"brightness": 80
}
}
批量操作
按顺序执行多个操作。
示例请求：
POST /api/actions/batch
{
"actions": [
{
"action": "turn_on_lights",
"parameters": {
"room": "living_room"
}
},
{
"action": "set_temperature",
"parameters": {
"temperature": 22
}
}
]
}
查询函数
获取可用操作
返回所有可用操作的列表。
响应示例：
{
"actions": [
{
"name": "turn_on_lights",
"parameters": ["room", "brightness"],
"description": "Turns on lights in specified room"
},
{
"name": "set_temperature",
"parameters": ["temperature"],
"description": "Sets temperature in current context"
}
]
}
上下文查询
GET /api/context?type=current
检索上下文信息。
响应示例：
{
"current_context": {
"user": "john",
"location": "kitchen",
"time": "morning",
"activity": "cooking"
}
}
WebSocket 事件
服务器支持通过 WebSocket 连接进行实时更新。
// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received update:', data);
};
支持的事件
state_change ：系统状态改变时发出context_update ：上下文更新时发出action_executed ：操作完成时发出error ：发生错误时发出
事件数据示例：
{
"event": "state_change",
"data": {
"previous_state": {
"lights": "off"
},
"current_state": {
"lights": "on"
},
"timestamp": "2024-03-20T10:30:00Z"
}
}
错误处理
所有端点都返回标准 HTTP 状态代码：
- 200：成功
- 400：错误请求
- 401：未授权
- 403：禁止访问
- 404：未找到
- 500：内部服务器错误
错误响应格式：
{
"error": {
"code": "INVALID_PARAMETERS",
"message": "Missing required parameter: room",
"details": {
"missing_fields": ["room"]
}
}
}
速率限制
API 实施速率限制以防止滥用：
- 对于常规端点，每个 IP 每分钟 100 个请求
- 每个 IP 每分钟 1000 个 WebSocket 连接请求
当超出速率限制时，服务器返回：
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"reset_time": "2024-03-20T10:31:00Z"
}
}
示例用法
使用 curl
# Get current state
curl -X GET \
http://localhost:3000/api/state \
-H 'Authorization: ApiKey your_api_key_here'
# Execute action
curl -X POST \
http://localhost:3000/api/action \
-H 'Authorization: ApiKey your_api_key_here' \
-H 'Content-Type: application/json' \
-d '{
"action": "turn_on_lights",
"parameters": {
"room": "living_room",
"brightness": 80
}
}'
使用 JavaScript
// Execute action
async function executeAction() {
const response = await fetch('http://localhost:3000/api/action', {
method: 'POST',
headers: {
'Authorization': 'ApiKey your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
action: 'turn_on_lights',
parameters: {
room: 'living_room',
brightness: 80
}
})
});
const data = await response.json();
console.log('Action result:', data);
}
发展
# Development mode with hot reload
npm run dev
# Build project
npm run build
# Production mode
npm run start
# Run tests
npx jest --config=jest.config.cjs
# Run tests with coverage
npx jest --coverage
# Lint code
npm run lint
# Format code
npm run format
故障排除
常见问题
- Node.js 版本（
toSorted is not a function ）- **解决方案：**更新至 Node.js 20.10.0+ GXP39
- 连接问题
- 验证 Home Assistant 是否正在运行
- 检查
HASS_HOST可访问性 - 验证令牌权限
- 确保 WebSocket 连接以实现实时更新
- 附加组件管理问题
- HACS集成问题
- 验证 HACS 安装
- 检查 HACS 集成状态
- 验证存储库访问权限
- 自动化问题
- 验证实体可用性
- 检查触发条件
- 验证服务调用
- 监控执行日志
项目状态
✅完成
- 实体、楼层和区域访问
- 设备控制（灯光、气候、盖子、开关、触点）
- 附加组件管理系统
- 通过 HACS 进行包裹管理
- 高级自动化配置
- 基本状态管理
- 错误处理和验证
- Docker 容器化
- Jest 测试设置
- TypeScript 集成
- 环境变量管理
- 家庭助理 API 集成
- 项目文档
🚧进行中
- 用于实时更新的 WebSocket 实现
- 增强的安全功能
- 刀具组织优化
- 性能优化
- 资源上下文整合
- API文档生成
- 多平台桌面集成
- 高级错误恢复
- 自定义提示测试
- 增强的 macOS 集成
- 类型安全改进
- 测试覆盖范围扩展
贡献
- 分叉存储库
- 创建功能分支
- 实施您的更改
- 添加新功能测试
- 确保所有测试通过
- 提交拉取请求
资源
执照
MIT 许可证 - 请参阅许可证文件