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

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

作为您 Home Assistant 实例与语言学习模型（LLMs）之间的强大桥梁，它通过模型上下文协议（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('收到更新:', data);
};

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

目录

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

核心功能

核心功能 🎮

• 智能设备控制
  • 💡 灯光：亮度、色温、RGB 颜色
  • 🌡️ 气候：温度、空调模式、风扇模式、湿度
  • 🚪 窗帘/百叶窗：位置和倾斜角度控制
  • 🔌 开关：开/关控制
  • 🚨 传感器与门磁：状态监测
  • 🎵 媒体播放器：播放控制、音量调节、源选择
  • 🌪️ 风扇：风速、摆动、风向控制
  • 🔒 门锁：上锁/解锁控制
  • 🧹 扫地机器人：启动、停止、返回基站
  • 📹 摄像头：移动侦测、截图

系统管理 🛠️

• 附加组件管理

  • 浏览可用的附加组件
  • 安装/卸载附加组件
  • 启动/停止/重启附加组件
  • 版本管理
  • 配置访问

• 软件包管理（HACS）

  • 与 Home Assistant 社区商店集成
  • 支持多种类型的软件包：
    • 自定义集成
    • 前端主题
    • Python 脚本
    • AppDaemon 应用
    • NetDaemon 应用
  • 版本控制和更新
  • 仓库管理

• 自动化管理

  • 创建和编辑自动化规则
  • 高级配置选项：
    • 多种触发类型
    • 复杂条件
    • 动作序列
    • 执行模式
  • 复制和修改现有自动化
  • 启用/禁用自动化规则
  • 手动触发自动化

架构特点 🏗️

• 智能组织

  • 按区域和楼层对设备分组
  • 状态监控和查询
  • 智能上下文感知
  • 历史数据访问

• 健壮架构

  • 全面的错误处理
  • 状态验证
  • 安全的 API 集成
  • TypeScript 类型安全
  • 广泛的测试覆盖

先决条件

• Node.js 20.10.0 或更高版本
• NPM 包管理器
• Docker Compose 用于容器化
• 正在运行的 Home Assistant 实例
• Home Assistant 长效访问令牌（如何获取令牌）
• 已安装 HACS 以使用软件包管理功能
• 具有 Supervisor 访问权限以便进行附加组件管理

安装

基本设置

# 克隆仓库
git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp

# 安装依赖
npm install

# 构建项目
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 配置
   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
   

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：环境（生产/开发）
• 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           # 测试令牌

配置文件

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",  // 或 "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": "当检测到移动时打开灯",
    "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": "在指定房间打开灯光"
    },
    {
      "name": "set_temperature",
      "parameters": ["temperature"],
      "description": "设置当前环境的温度"
    }
  ]
}

上下文查询

GET /api/context?type=current

获取上下文信息。

示例响应：

{
  "current_context": {
    "user": "john",
    "location": "厨房",
    "time": "早晨",
    "activity": "做饭"
  }
}

WebSocket 事件

服务器支持通过 WebSocket 连接进行实时更新。

// 客户端连接示例
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('收到更新:', data);
};

支持的事件

• state_change: 当系统状态发生变化时触发
• context_update: 当上下文更新时触发
• action_executed: 当某个操作完成时触发
• error: 当发生错误时触发

事件数据示例：

{
  "event": "state_change",
  "data": {
    "previous_state": {
      "lights": "关"
    },
    "current_state": {
      "lights": "开"
    },
    "timestamp": "2024-03-20T10:30:00Z"
  }
}

错误处理

所有端点均返回标准 HTTP 状态码：

• 200：成功
• 400：请求错误
• 401：未授权
• 403：禁止访问
• 404：未找到
• 500：服务器内部错误

错误响应格式：

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "缺少必填参数：room",
    "details": {
      "missing_fields": ["room"]
    }
  }
}

速率限制

API 实施了速率限制以防止滥用：

• 普通端点每 IP 地址每分钟 100 次请求
• WebSocket 连接每 IP 地址每分钟 1000 次请求

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

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "请求次数过多",
    "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": "客厅",
      "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: '客厅',
        brightness: 80
      }
    })
  });
  
  const data = await response.json();
  console.log('操作结果:', 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

故障排除

常见问题

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 是否可访问
   • 验证 Token 权限
   • 确保 WebSocket 连接用于实时更新

3. 附加组件管理问题

   • 验证 Supervisor 的访问权限
   • 检查附加组件的兼容性
   • 确认系统资源是否充足

4. HACS 集成问题

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

5. 自动化问题

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

项目状态

✅ 已完成

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

🚧 进行中

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

贡献

1. 克隆仓库并创建分支
2. 实现所需功能
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交 Pull Request

资源

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

许可证

MIT 许可证 - 详见 LICENSE 文件

Home Assistant MCP 快速上手指南

Home Assistant MCP 是一个基于 Model Context Protocol (MCP) 的服务器，旨在将本地 Home Assistant 实例与大语言模型（LLM）连接。通过它，你可以使用自然语言控制智能家居设备、管理自动化脚本并实时监控设备状态。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 运行环境:
  • Node.js >= 20.10.0
  • NPM >= 7.0.0
  • Docker Compose >= 1.27.0 (推荐用于部署)
• Home Assistant 实例:
  • 正在运行的 Home Assistant 服务。
  • Long-Lived Access Token: 需要在 HA 用户配置中生成一个长期有效的访问令牌。
  • HACS: 已安装 Home Assistant Community Store (用于包管理功能)。
  • Supervisor: 需要 Supervisor 权限以管理 Add-ons。

安装步骤

推荐使用 Docker Compose 进行部署，以获得一致且易于维护的环境。

1. 克隆项目

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

2. 配置环境变量

复制示例配置文件并根据你的实际情况修改：

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

3. 启动服务

使用 Docker Compose 构建并后台运行容器：

docker compose up -d

查看日志以确保服务正常启动：

docker compose logs -f

验证安装: 服务启动后，可通过访问 http://localhost:3000/health 检查健康状态。

(可选) 源码安装方式: 如果不使用 Docker，可执行以下命令：

npm install
npm run build
npm start

基本使用

安装完成后，该服务器即可作为 MCP Server 被 LLM 客户端（如 Claude Desktop）调用。

1. 配置 LLM 客户端

若要在 Claude Desktop 中使用，需在其配置文件中添加以下内容（注意：此方式直接运行 Node，不使用 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"
    }
  }
}

2. 功能示例

配置成功后，你可以在对话中直接使用自然语言指令，MCP 会自动转换为相应的 API 调用：

• 控制设备:

  "把客厅的灯打开，亮度调到 50%。" (对应工具调用：control -> turn_on, entity_id: light.living_room, brightness: 128)

• 查询状态:

  "现在卧室的温度是多少？" (对应工具调用：查询 sensor 实体状态)

• 管理自动化:

  "创建一个新自动化：当检测到运动时打开走廊灯。" (对应工具调用：automation_config -> create)

• 实时订阅 (SSE): 开发者也可通过 HTTP 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('收到更新:', data);
  };
  

现在，你的 Home Assistant 已经可以通过大模型进行智能交互了。