家用型模型上下文协议服务器

该服务器使用MCP协议与LLM应用程序共享本地Home Assistant实例的访问权限。

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

许可证 Node.js Docker Compose 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('Update received:', 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/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp

# 安装依赖
npm install

# 构建项目
npm run build

Docker设置（推荐）

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

克隆仓库：

git clone https://github.com/tevonsb/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：环境（production/development）
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     # 环境（production/development）
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桌面（或其他客户端）

要使用您的新Home Assistant MCP服务器，您可以将其作为客户端添加。添加以下配置。请注意，这将使MCP在Claude内部运行，并且不适用于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('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实施速率限制以防止滥用：

每分钟100次请求/IP针对常规端点
每分钟1000次请求/IP针对WebSocket连接

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

{
  "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('Action result:', 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文件

tevonsb/homeassistant-mcp

星标增长

证据时间轴

家用型模型上下文协议服务器

功能

使用SSE实现实时更新

快速SSE示例

目录

关键功能

核心功能 🎮

系统管理 🛠️

架构特性 🏗️

先决条件

安装

基本设置

Docker设置（推荐）

Docker配置

Docker Compose环境变量

配置

环境变量

配置文件

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

API参考

设备控制

常见实体控制

灯光控制

插件管理

列出可用插件

安装插件

管理插件状态

软件包管理

列出HACS软件包

安装软件包

自动化管理

创建自动化

复制自动化

核心功能

状态管理

上下文更新

动作端点

执行动作

批量动作

查询功能

获取可用动作

上下文查询

WebSocket事件

支持的事件

错误处理

速率限制

示例用法

使用curl

使用JavaScript

开发

故障排除

常见问题

项目状态

贡献

资源

许可证