Model Context Protocol Server for Home Assistant

Home Assistant 的 MCP 服务

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

这是 Home Assistant 实例与大语言模型（LLM）之间的强大桥梁，可通过 Model Context Protocol（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 系统的完整文档。

目录

• 主要功能
• 先决条件
• 安装
  • 基本设置
  • Docker 设置（推荐）
• 配置
• 开发
• API 参考
  • 设备控制
  • 附加组件管理
  • 软件包管理
  • 自动化管理
• 自然语言集成
• 故障排除
• 项目状态
• 贡献
• 资源
• 许可证

主要功能

核心功能 🎮

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

安装

基本设置

# Clone the repository
git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp

# Install dependencies
npm install

# Build the project
npm run build

Docker 设置（推荐）

项目支持 Docker，可在不同平台上轻松部署并保持环境一致。

1. 克隆代码库：

   git clone https://github.com/tevonsb/homeassistant-mcp.git
   cd homeassistant-mcp
   

2. 配置环境：

   cp .env.example .env
   

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

   # 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
   

3. 使用 Docker Compose 构建并运行：

   # 构建并启动容器
   docker compose up -d
   
   # 查看日志
   docker compose logs -f
   
   # 停止服务
   docker compose down
   

4. 验证安装： 服务器现在应已在 http://localhost:3000 运行。你可以通过 http://localhost:3000/health 检查健康状态端点。

5. 更新应用程序：

   # 拉取最新更改
   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：环境（production/development）
• 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

配置文件

1. 开发环境：将 .env.example 复制为 .env.development
2. 生产环境：将 .env.example 复制为 .env.production
3. 测试环境：将 .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

故障排除

常见问题

1. Node.js 版本（toSorted is not a function）

   • **解决方案：**更新至 Node.js 20.10.0+

   nvm install 20.10.0
   nvm use 20.10.0
   

2. 连接问题

   • 确认 Home Assistant 正在运行
   • 检查 HASS_HOST 是否可访问
   • 验证令牌权限
   • 确保 WebSocket 连接可用于实时更新

3. 附加组件管理问题

   • 确认可访问 Supervisor
   • 检查附加组件兼容性
   • 验证系统资源

4. HACS 集成问题

   • 确认已安装 HACS
   • 检查 HACS 集成状态
   • 验证仓库访问权限

5. 自动化问题

   • 确认实体可用
   • 检查触发条件
   • 验证服务调用
   • 监控执行日志

项目状态

✅ 已完成

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

🚧 进行中

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

参与贡献

1. Fork 仓库
2. 创建功能分支
3. 实现更改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交拉取请求

资源

• MCP 文档
• Home Assistant 文档
• HA REST API
• HACS 文档
• TypeScript 文档

许可证

MIT 许可证 - 请参阅 LICENSE 文件