Home Assistant 模型上下文协议服务器

该服务器使用MCP协议，使语言学习模型（LLM）应用程序能够访问本地Home Assistant实例。

这是一个强大的桥梁，连接您的Home Assistant实例和语言学习模型（LLM），通过模型上下文协议（MCP）实现智能家居设备的自然语言控制和监控。该服务器提供了一个全面的API，用于管理您的整个Home Assistant生态系统，从设备控制到系统管理。

许可证 Node.js NPM TypeScript 测试覆盖率

功能特点

🎮 设备控制：通过自然语言控制任何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('收到更新:', data);
};

有关SSE系统的完整文档，请参阅SSE_API.md。

主要功能

核心功能 🎮

智能设备控制
- 💡 灯光：亮度、色温、RGB颜色
- 🌡️ 气候：温度、HVAC模式、风扇模式、湿度
- 🚪 窗帘：位置和倾斜控制
- 🔌 开关：开/关控制
- 🚨 传感器与接触器：状态监控
- 🎵 媒体播放器：播放控制、音量、源选择
- 🌪️ 风扇：速度、摆动、方向
- 🔒 锁：锁定/解锁控制
- 🧹 吸尘器：启动、停止、返回底座
- 📹 摄像头：运动检测、快照

系统管理 🛠️

插件管理
- 浏览可用插件
- 安装/卸载插件
- 启动/停止/重启插件
- 版本管理
- 配置访问
包管理（HACS）
- 与Home Assistant社区商店集成
- 支持多种包类型：
  - 自定义集成
  - 前端主题
  - Python脚本
  - AppDaemon应用
  - NetDaemon应用
- 版本控制和更新
- 仓库管理
自动化管理
- 创建和编辑自动化
- 高级配置选项：
  - 多种触发器类型
  - 复杂条件
  - 动作序列
  - 执行模式
- 复制和修改现有自动化
- 启用/禁用自动化规则
- 手动触发自动化

架构特点 🏗️

智能组织
- 基于区域和楼层的设备分组
- 状态监控和查询
- 智能上下文感知
- 历史数据访问
健壮的架构
- 全面的错误处理
- 状态验证
- 安全的API集成
- TypeScript类型安全
- 广泛的测试覆盖率

先决条件

Node.js 20.10.0或更高版本
NPM 包管理器
Docker Compose 用于容器化
运行中的Home Assistant实例
Home Assistant长期访问令牌（如何获取令牌）
安装HACS以使用包管理功能
Supervisor访问权限以管理插件

安装

基本设置

# 克隆仓库
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

# 安装依赖
npm install

# 构建项目
npm run build

Docker设置（推荐）

该项目包含Docker支持，便于在不同平台上轻松部署和保持一致的环境。

克隆仓库：

git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp

配置环境：

cp .env.example .env

使用您的Home Assistant配置编辑.env文件：

# Home Assistant配置
HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket

# 服务器配置
PORT=3000
NODE_ENV=production
DEBUG=false

使用Docker Compose构建并运行：

# 构建并启动容器
docker compose up -d

# 查看日志
docker compose logs -f

# 停止服务
docker compose down

验证安装： 服务器现在应该在http://localhost:3000上运行。您可以检查健康端点http://localhost:3000/health。

更新应用程序：

# 拉取最新更改
git pull

# 重新构建并重启容器
docker compose up -d --build

Docker配置

Docker设置包括：

多阶段构建以优化镜像大小
容器监控的健康检查
用于环境配置的卷挂载
失败时自动重启容器
暴露端口3000以供API访问

Docker Compose环境变量

所有环境变量都可以在.env文件中配置。支持以下变量：

HASS_HOST：您的Home Assistant实例URL
HASS_TOKEN：Home Assistant的长期访问令牌
HASS_SOCKET_URL：Home Assistant的WebSocket URL
PORT：服务器端口（默认：3000）
NODE_ENV：环境（生产/开发）
DEBUG：启用调试模式（true/false）

配置

环境变量

# Home Assistant配置
HASS_HOST=http://homeassistant.local:8123  # 您的Home Assistant实例URL
HASS_TOKEN=your_home_assistant_token       # 长期访问令牌
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # WebSocket URL

# 服务器配置
PORT=3000                # 服务器端口（默认：3000）
NODE_ENV=production     # 环境（生产/开发）
DEBUG=false            # 启用调试模式

# 测试配置
TEST_HASS_HOST=http://localhost:8123  # 测试实例URL
TEST_HASS_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",  // 或 "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",  // 或 "stop", "restart"
  "slug": "core_configurator"
}

包管理

列出HACS包

{
  "tool": "package",
  "action": "list",
  "category": "integration"  // 或 "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

使用新信息更新当前上下文。

示例请求：

POST /api/context
{
  "user": "john",
  "location": "kitchen",
  "time": "morning",
  "activity": "cooking"
}

操作端点

执行操作

POST /api/action

执行指定的操作并使用给定的参数。

示例请求：

POST /api/action
{
  "action": "turn_on_lights",
  "parameters": {
    "room": "living_room",
    "brightness": 80
  }
}

批量操作

POST /api/actions/batch

按顺序执行多个操作。

示例请求：

POST /api/actions/batch
{
  "actions": [
    {
      "action": "turn_on_lights",
      "parameters": {
        "room": "living_room"
      }
    },
    {
      "action": "set_temperature",
      "parameters": {
        "temperature": 22
      }
    }
  ]
}

查询功能

获取可用操作

GET /api/actions

返回所有可用操作的列表。

示例响应：

{
  "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连接支持实时更新。

// 客户端连接示例
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('收到更新:', 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次请求
WebSocket连接每分钟每个IP 1000次请求

当超过速率限制时，服务器返回：

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "reset_time": "2024-03-20T10:31:00Z"
  }
}

使用示例

使用curl

# 获取当前状态
curl -X GET \
  http://localhost:3000/api/state \
  -H 'Authorization: ApiKey your_api_key_here'

# 执行操作
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

// 执行操作
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('操作结果:', data);
}

开发

# 开发模式，带热重载
npm run dev

# 构建项目
npm run build

# 生产模式
npm run start

# 运行测试
npx jest --config=jest.config.cjs

# 带覆盖率的测试运行
npx jest --coverage

# 代码检查
npm run lint

# 代码格式化
npm run format

故障排除

常见问题

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的可访问性
- 验证令牌权限
- 确保WebSocket连接以进行实时更新
插件管理问题
- 验证Supervisor访问权限
- 检查插件兼容性
- 验证系统资源
HACS集成问题
- 验证HACS安装
- 检查HACS集成状态
- 验证仓库访问权限
自动化问题
- 验证实体可用性
- 检查触发器条件
- 验证服务调用
- 监控执行日志

项目状态

✅ 已完成

实体、楼层和区域访问
设备控制（灯光、气候、窗帘、开关、接触器）
插件管理系统
通过HACS的包管理
高级自动化配置
基本状态管理
错误处理和验证
Docker容器化
Jest测试设置
TypeScript集成
环境变量管理
Home Assistant API集成
项目文档

🚧 进行中

用于实时更新的WebSocket实现
增强的安全功能
工具组织优化
性能优化
资源上下文集成
API文档生成
多平台桌面集成
高级错误恢复
自定义提示测试
增强的macOS集成
类型安全改进
测试覆盖率扩展

贡献

分叉仓库
创建功能分支
实现您的更改
为新功能添加测试
确保所有测试通过
提交拉取请求

资源

许可证

MIT许可证 - 请参阅LICENSE文件

Home Assistant 模型上下文协议服务器

功能特点

使用SSE的实时更新

快速SSE示例

目录

主要功能

核心功能 🎮

系统管理 🛠️

架构特点 🏗️

先决条件

安装

基本设置

Docker设置（推荐）

Docker配置

Docker Compose环境变量

配置

环境变量

配置文件

添加到Claude Desktop（或其他客户端）

API参考

设备控制

常见实体控制

灯光控制

插件管理

列出可用插件

安装插件

管理插件状态

包管理

列出HACS包

安装包

自动化管理

创建自动化

复制自动化

核心功能

状态管理

上下文更新

操作端点

执行操作

批量操作

查询功能

获取可用操作

上下文查询

WebSocket事件

支持的事件

错误处理

速率限制

使用示例

使用curl

使用JavaScript

开发

故障排除

常见问题

项目状态

贡献

资源

许可证

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐