使用说明

项目简介

Home Assistant MCP Server 是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在连接 Home Assistant 智能家居系统与大型语言模型 (LLM) 应用。它允许用户通过自然语言与 LLM 客户端交互，进而控制和监控 Home Assistant 管理的智能家居设备、自动化场景等。

主要功能点

智能设备控制: 通过自然语言指令控制 Home Assistant 中的各类智能设备，如灯光、温控、开关、传感器等。
实时状态更新: 通过 Server-Sent Events (SSE) 技术，为客户端提供 Home Assistant 设备状态的实时更新。
自动化管理: 支持对 Home Assistant 自动化规则的创建、编辑、启用/禁用和手动触发等管理功能。
插件和包管理: 集成了 Home Assistant Add-on 和 HACS 包管理功能，方便用户扩展 Home Assistant 功能。
安全机制: 提供基于 Token 的身份验证和速率限制，保障服务器安全。
多种部署方式: 支持基础安装和 Docker 容器化部署，适应不同用户的需求。

安装步骤

克隆仓库

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

安装依赖
```
npm install
```
构建项目
```
npm run build
```

配置环境变量 复制 '.env.example' 文件并重命名为 '.env'，根据您的 Home Assistant 环境配置以下变量：

HASS_HOST=http://homeassistant.local:8123  # Home Assistant 实例地址
HASS_TOKEN=your_home_assistant_token       # Home Assistant 长期访问令牌
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # Home Assistant WebSocket 地址
PORT=3000                # 服务器端口，默认为 3000

启动服务器

基础方式:
```
npm run start
```

Docker 方式 (推荐):

docker compose up -d

服务器配置 (MCP 客户端)

MCP 客户端需要配置以下 JSON 信息以连接到 Home Assistant MCP Server：

{
  "homeassistant-mcp": {
    "server name": "Home Assistant MCP Server",
    "command": "node",
    "args": ["<path/to/your/dist/folder>"],  // 将 <path/to/your/dist/folder> 替换为项目 dist 目录的绝对路径
    "env": {
      "HASS_HOST": "http://homeassistant.local:8123",  // 您的 Home Assistant 实例地址
      "HASS_TOKEN": "your_home_assistant_token",   // 您的 Home Assistant 长期访问令牌
      "PORT": "3000"                           // MCP 服务器端口，与 .env 文件中配置的 PORT 一致
    }
  }
}

基本使用方法

服务器启动后，您可以通过 MCP 客户端（如 Claude Desktop）或直接通过 HTTP 请求访问 API 接口。

列出设备: 访问 '/list_devices' 接口获取 Home Assistant 设备列表。
设备控制: 通过 POST 请求访问 '/control' 接口，并按照 API 文档提供 JSON 格式的控制指令，例如控制灯光开关、调节温度等。
订阅事件: 客户端可以通过 SSE 订阅 '/subscribe_events' 接口，接收 Home Assistant 状态变化的实时推送。

详细的 API 使用方法请参考仓库中的 API 文档。

关键词