Home Assistant LLM 集成

@drejom/homeassistant-mcp

0 Stars 76 次浏览 drejom 更新于 2026-08-23

启用 Home Assistant 与语言学习模型 (LLMs) 之间的无缝集成，允许使用自然语言进行智能家居控制和自动化管理交互。

开发者工具

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

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

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

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

功能

🎮 设备控制：通过自然语言控制任何 Home Assistant 设备
🔄 实时更新：通过 Server-Sent Events (SSE) 获取即时更新
🤖 自动化管理：创建、更新和管理自动化
📊 状态监控：跟踪和查询设备状态
🔐 安全：基于令牌的身份验证和速率限制
📱 移动就绪：适用于任何支持 HTTP 的客户端

使用 SSE 进行实时更新

服务器包含一个强大的 Server-Sent Events (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_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 访问权限以进行插件管理

安装

通过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

配置环境:

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: 启用调试模式（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

更新当前上下文以包含新信息。

示例请求：

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

// 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 对 WebSocket 连接的请求次数不超过 1000 次

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

{
  "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+
```
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 文件

查看源码项目主页

服务介绍

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

功能

使用 SSE 进行实时更新

快速 SSE 示例

目录

主要功能

核心功能 🎮

系统管理 🛠️

架构特性 🏗️

前提条件

安装

通过Smithery安装

基本设置

Docker设置（推荐）

Docker 配置

Docker Compose 环境变量

配置

环境变量

配置文件

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

API 参考

设备控制

常见实体控制

灯光控制

插件管理

列出可用插件

安装插件

管理插件状态

包管理

列出 HACS 包

安装包

自动化管理

创建自动化

复制自动化

核心功能

状态管理

上下文更新

动作端点

执行动作

批量动作

查询功能

获取可用动作

上下文查询

WebSocket 事件

支持的事件

错误处理

速率限制

示例用法

使用 curl

使用 JavaScript

开发

故障排除

常见问题

项目状态

参与贡献

资源

许可证

相关 MCP 服务

开源版 与 企业版

企业版（含 FDE 交付）

技能定制开发服务

开源版与企业版