家庭助手-MCP

Name: 家庭助手-MCP
Author: tevonsb

作者：tevonsb478 星标更新：2025-02-01

安装使用来源：spider==github.com

项目介绍

Home Assistant 的 Model Context Protocol 服务器

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

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

功能

🎮 设备控制：通过自然语言控制任何 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_API.md 以获取完整的 SSE 系统文档。

关键功能

核心功能 🎮

智能设备控制
- 💡 灯光：亮度、色温、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

编辑 .env 文件，填写您的 Home Assistant 配置：

# 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：启用调试模式（真/假）

配置

环境变量

# 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": "当检测到运动时打开灯光",
    "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": "在指定房间打开灯光"
    },
    {
      "name": "set_temperature",
      "parameters": ["temperature"],
      "description": "设置当前上下文的温度"
    }
  ]
}

上下文查询

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": "缺少必需的参数：room",
    "details": {
      "missing_fields": ["room"]
    }
  }
}

速率限制

API 实现了速率限制以防止滥用：

每分钟每 IP 100 次请求（常规端点）
每分钟每 IP 1000 次请求（WebSocket 连接）

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

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "请求过多",
    "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

家庭助手-MCP

项目介绍

Home Assistant 的 Model Context Protocol 服务器

功能

使用 SSE 实现实时更新

快速 SSE 示例

目录

关键功能

核心功能 🎮

系统管理 🛠️

架构特性 🏗️

前提条件

安装

基本设置

Docker 设置（推荐）

Docker 配置

Docker Compose 环境变量

配置

环境变量

配置文件

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

API 参考

设备控制

常用实体控制

灯光控制

附加组件管理

列出可用附加组件

安装附加组件

管理附加组件状态

包管理

列出 HACS 包

安装包

自动化管理

创建自动化

复制自动化

核心功能

状态管理

上下文更新

动作端点

执行动作

批量动作

查询功能

获取可用动作

上下文查询

WebSocket 事件

支持的事件

错误处理

速率限制

示例用法

使用 curl

使用 JavaScript