Home Assistant MCP控制面板

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

home-automation-and-iot

283 查看 · 2026-07-07 更新

简介

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

简介

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

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

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

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

特性

🎮 设备控制：通过自然语言控制任何 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 系统的完整文档，请参见 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访问权限

安装

基础设置

# 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

根据你的 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 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 次请求
WebSocket 连接每分钟每个 IP 地址 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

Home Assistant MCP控制面板

简介

简介

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

特性

使用 SSE 实现实时更新

快速 SSE 示例

目录

主要特性

核心功能 🎮

系统管理 🛠️

架构特性 🏗️

前提条件

安装

基础设置

Docker 设置 (推荐)

Docker 配置

Docker Compose 环境变量

配置

环境变量

配置文件

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

API 参考

设备控制

常见实体控制

灯光控制

插件管理

列出可用插件

安装插件

管理插件状态

包管理

列出 HACS 包

安装包

自动化管理

创建自动化

复制自动化

核心功能

状态管理

上下文更新

动作端点

执行动作

批量动作

查询功能

获取可用动作

上下文查询

WebSocket 事件

支持的事件

错误处理

速率限制

使用示例

使用 curl

使用 JavaScript

开发

故障排除

常见问题

项目状态

参与贡献

资源

许可证

来源