使用说明

项目简介

Home Assistant MCP Server 是一个为 Home Assistant 设计的集成工具，它基于模型上下文协议 (MCP) 构建，旨在为大型语言模型 (LLM) 客户端提供一个灵活且标准化的接口，以便访问和控制您的智能家居设备。该服务器使用 Bun 运行时构建，追求高性能和资源效率。

主要功能点

设备控制: 通过 REST API 提供基本的 Home Assistant 设备控制能力。
实时更新: 支持 WebSocket 和 Server-Sent Events (SSE) 用于设备状态的实时更新。
自动化管理: 提供简单的自动化规则管理功能。
安全认证: 采用 JWT (JSON Web Token) 认证机制，保障访问安全。
可选语音功能: 集成可选的语音处理功能，包括唤醒词检测、语音转文本 (STT)，并支持 GPU 加速以提升语音处理速度（需要额外配置）。

安装步骤

克隆仓库:

git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp

环境配置:

运行环境设置脚本，根据需要选择开发或生产环境，并可选择是否强制覆盖现有配置文件。

./scripts/setup-env.sh

或指定环境：

NODE_ENV=production ./scripts/setup-env.sh

配置 Home Assistant 连接:
- 编辑 '.env' 文件，配置您的 Home Assistant 实例信息，务必设置 'HASS_TOKEN' (Home Assistant 长期访问令牌)。

Docker 部署 (推荐):

构建 Docker 镜像 (可选择是否包含语音功能和 GPU 支持)：

./docker-build.sh  # 标准构建
./docker-build.sh --speech # 包含语音功能
./docker-build.sh --speech --gpu # 包含语音功能和GPU支持

启动 Docker 容器：

docker compose up -d # 标准启动
docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d # 包含语音功能

服务器配置 (MCP 客户端)

MCP 客户端需要配置与 Home Assistant MCP Server 建立连接的命令和参数。以下是一些客户端配置示例，请根据您的 MCP 客户端进行相应配置。

Cursor 集成配置示例 (.cursor/config/config.json):

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bun",
      "args": ["run", "start"],
      "cwd": "${workspaceRoot}",
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

'server name': 'homeassistant-mcp' (服务器名称，客户端内唯一标识)
'command': 'bun' (启动服务器的命令，这里使用 Bun 运行时)
'args': '["run", "start"]' (传递给启动命令的参数，'run start' 表示运行 'bun run start' 启动服务器)
'cwd': '${workspaceRoot}' (工作目录，设置为客户端的工作区根目录)
'env': '{ "NODE_ENV": "development" }' (环境变量，设置为开发环境)

Claude Desktop 集成配置示例 (Claude 配置文件):

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bun",
      "args": ["run", "start", "--port", "8080"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

'server name': 'homeassistant-mcp' (服务器名称，客户端内唯一标识)
'command': 'bun' (启动服务器的命令，这里使用 Bun 运行时)
'args': '["run", "start", "--port", "8080"]' (传递给启动命令的参数，'run start --port 8080' 表示运行 'bun run start --port 8080' 启动服务器，并指定端口为 8080)
'env': '{ "NODE_ENV": "production" }' (环境变量，设置为生产环境)

基本使用方法

Home Assistant MCP Server 启动后，MCP 客户端可以通过配置的命令和参数连接到服务器。服务器提供了一系列工具 (Tools) 和资源 (Resources)，客户端可以调用这些工具来管理 Home Assistant 设备，例如：

列出设备: 使用 'list_devices' 工具获取 Home Assistant 中所有设备的列表。
控制设备: 使用 'control' 工具控制特定设备的状态，例如开关灯、调节温度等。
订阅事件: 使用 'subscribe_events' 工具订阅 Home Assistant 的事件流，实时接收设备状态更新。

更多详细的 API 文档和高级功能使用指南，请参考仓库内的 'docs/' 目录。

关键词