homeassistant-mcp

家庭助理的模型上下文协议服务器

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

您的 Home Assistant 实例与语言学习模型 (LLM) 之间的强大桥梁，通过模型上下文协议 (MCP) 实现对智能家居设备的自然语言控制和监控。该服务器提供全面的 API，用于管理您的整个 Home Assistant 生态系统，涵盖从设备控制到系统管理的各个方面。

Node.js Docker Compose 新公共管理 TypeScript 测试覆盖率

特征

🎮设备控制：通过自然语言控制任何家庭助理设备
🔄实时更新：通过服务器发送事件（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 颜色
- 🌡️气候：温度、暖通空调模式、风扇模式、湿度
- 🚪封面：位置和倾斜控制
- 🔌开关：开/关控制
- 🚨传感器和接触器：状态监控
- 🎵媒体播放器：播放控制、音量、源选择
- 🌪️风扇：速度、摆动、方向
- 🔒锁：锁定/解锁控制
- 🧹吸尘器：启动、停止、返回基座
- 📹相机：运动检测、快照

系统管理🛠️

附加组件管理
- 浏览可用的附加组件
- 安装/卸载附加组件
- 启动/停止/重启附加组件
- 版本管理
- 配置访问
包裹管理（HACS）
- 与 Home Assistant Community Store 集成
- 多种封装类型支持：
  - 自定义集成
  - 前端主题
  - Python 脚本
  - AppDaemon 应用程序
  - NetDaemon 应用程序
- 版本控制和更新
- 存储库管理
自动化管理
- 创建和编辑自动化
- 高级配置选项：
  - 多种触发类型
  - 复杂条件
  - 动作序列
  - 执行模式
- 复制并修改现有的自动化
- 启用/禁用自动化规则
- 手动触发自动化

架构特点🏗️

智能组织
- 基于区域和楼层的设备分组
- 状态监控与查询
- 智能情境感知
- 历史数据访问
稳健的架构
- 全面的错误处理
- 状态验证
- 安全 API 集成
- TypeScript 类型安全
- 广泛的测试覆盖范围

先决条件

Node.js 20.10.0 或更高版本
NPM包管理器
Docker Compose用于容器化
运行Home Assistant实例
Home Assistant 长期访问令牌（如何获取令牌）
安装HACS以实现包裹管理功能
附加组件管理的主管访问权限

安装

基本设置

# 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 Configuration HASS_HOST=http://homeassistant.local:8123 HASS_TOKEN=your_home_assistant_token HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket # Server Configuration PORT=3000 NODE_ENV=production DEBUG=false
使用 Docker Compose 构建并运行：
# Build and start the containers docker compose up -d # View logs docker compose logs -f # Stop the service docker compose down
**验证安装：**服务器现在应该在http://localhost:3000上运行。您可以在http://localhost:3000/health检查健康端点。
更新应用程序：
# Pull the latest changes git pull # Rebuild and restart the containers docker compose up -d --build

Docker 配置

Docker 设置包括：

多阶段构建以获得最佳图像尺寸
容器监控的健康检查
用于环境配置的卷安装
失败时自动重启容器
暴露 3000 端口用于 API 访问

Docker Compose 环境变量

所有环境变量都可以在.env文件中配置。支持以下变量：

HASS_HOST ：您的 Home Assistant 实例 URL
HASS_TOKEN ：Home Assistant 的长期访问令牌
HASS_SOCKET_URL ：家庭助理的 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 每分钟 1000 个 WebSocket 连接请求

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

{
  "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+ GXP38
连接问题
- 验证 Home Assistant 是否正在运行
- 检查HASS_HOST可访问性
- 验证令牌权限
- 确保 WebSocket 连接以实现实时更新
附加组件管理问题
- 验证主管访问权限
- 检查附加组件兼容性
- 验证系统资源
HACS集成问题
- 验证 HACS 安装
- 检查 HACS 集成状态
- 验证存储库访问权限
自动化问题
- 验证实体可用性
- 检查触发条件
- 验证服务调用
- 监控执行日志

项目状态

✅完成

实体、楼层和区域访问
设备控制（灯光、气候、盖子、开关、触点）
附加组件管理系统
通过 HACS 进行包裹管理
高级自动化配置
基本状态管理
错误处理和验证
Docker 容器化
Jest 测试设置
TypeScript 集成
环境变量管理
家庭助理 API 集成
项目文档

🚧进行中

用于实时更新的 WebSocket 实现
增强的安全功能
刀具组织优化
性能优化
资源上下文整合
API文档生成
多平台桌面集成
高级错误恢复
自定义提示测试
增强的 macOS 集成
类型安全改进
测试覆盖范围扩展

贡献

分叉存储库
创建功能分支
实施您的更改
添加新功能测试
确保所有测试通过
提交拉取请求

资源

执照

MIT 许可证 - 请参阅许可证文件

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

访问家庭助理数据和控制设备（灯、开关、恒温器等）。

Related MCP Servers

Home Assistant MCP
allenporter
-
security
A
license
-
quality
Expose all Home Assistant voice intents through a Model Context Protocol Server allowing home control.
Last updated -
30
Python
Apache 2.0
Google Home MCP Server
jmagar
-
security
F
license
-
quality
Enables users to control Google Home smart plugs using the Smart Home API with OAuth2 authentication, offering real-time device state management and control operations.
Last updated -
1
TypeScript
SwitchBot MCP Server
genm
A
security
A
license
A
quality
Enables AI assistants to control SwitchBot devices, providing functionalities like device management, scene execution, and sensor information monitoring through the SwitchBot API.
Last updated -
3
JavaScript
ISC License
Home Assistant MCP Server
hekmon8
A
security
A
license
A
quality
A server that enables interaction with Home Assistant devices and automations through the Model Context Protocol, allowing users to monitor device states, control devices, trigger automations, and list entities.
Last updated -
4
29
JavaScript
MIT License

View all related MCP servers

家庭助理的模型上下文协议服务器

特征

使用 SSE 进行实时更新

快速 SSE 示例

目录

主要特点

核心功能🎮

系统管理🛠️

架构特点🏗️

先决条件

安装

基本设置

Docker 设置（推荐）

Docker 配置

Docker Compose 环境变量

配置

环境变量

配置文件

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

API 参考

设备控制

常见实体控制

灯光控制

附加组件管理

列出可用的附加组件

安装附加组件

管理附加组件状态

包管理

列出 HACS 包

安装包

自动化管理

创建自动化

重复自动化

核心功能

状态管理

上下文更新

行动端点

执行操作

批量操作

查询函数

获取可用操作

上下文查询

WebSocket 事件

支持的事件

错误处理

速率限制

示例用法

使用 curl

使用 JavaScript

发展

故障排除

常见问题

项目状态

贡献

资源

执照

Related MCP Servers

Home Assistant MCP

Google Home MCP Server

SwitchBot MCP Server

Home Assistant MCP Server

Appeared in Searches

New MCP Servers

MCP directory API