MCP 服务器

homeassistant-mcp

访问 Home Assistant 数据并控制设备（灯、开关、恒温器等）。

README

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

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

一个强大的桥梁，连接您的 Home Assistant 实例和语言学习模型 (LLM)，通过模型上下文协议 (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('Update received:', data);
};

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

主要特性

核心功能 🎮

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

系统管理 🛠️

插件管理
- 浏览可用插件
- 安装/卸载插件
- 启动/停止/重启插件
- 版本管理
- 配置访问
软件包管理 (HACS)
- 与 Home Assistant Community Store 集成
- 支持多种软件包类型：
  - 自定义集成
  - 前端主题
  - 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('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 个请求
对于 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('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 集成
类型安全改进
测试覆盖率扩展

贡献

Fork 仓库
创建一个功能分支
实现您的更改
为新功能添加测试
确保所有测试通过
提交 pull request

资源

许可证

MIT 许可证 - 请参阅 LICENSE 文件

homeassistant-mcp

README

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

功能特性

使用 SSE 进行实时更新

快速 SSE 示例

目录

主要特性

核心功能 🎮

系统管理 🛠️

架构特性 🏗️

先决条件

安装

基本设置

Docker 设置 (推荐)

Docker 配置

Docker Compose 环境变量

配置

环境变量

配置文件

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

API 参考

设备控制

常用实体控制

灯光控制

插件管理

列出可用插件

安装插件

管理插件状态

软件包管理

列出 HACS 软件包

安装软件包

自动化管理

创建自动化

复制自动化

核心功能

状态管理

上下文更新

操作端点

执行操作

批量操作

查询功能

获取可用操作

上下文查询

WebSocket 事件

支持的事件

错误处理

速率限制

使用示例

使用 curl

使用 JavaScript

开发

故障排除

常见问题

项目状态

贡献

资源

许可证

推荐服务器