Home Assistant MCP Server 使用说明

项目简介

Home Assistant MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在桥接大型语言模型 (LLM) 应用和 Home Assistant 智能家居系统。通过此服务器，LLM 应用能够以标准化的方式获取 Home Assistant 的设备状态、控制设备、触发自动化流程以及查询可用实体，从而实现智能家居的自然语言交互和控制。

主要功能点

获取设备状态: 允许 LLM 应用查询 Home Assistant 中指定实体的当前状态，例如灯的状态（开/关）、传感器数值等。
控制设备: 允许 LLM 应用控制 Home Assistant 中的设备，例如打开或关闭灯、开关等。
触发自动化: 允许 LLM 应用触发预先在 Home Assistant 中配置的自动化流程。
列entities列表: 允许 LLM 应用获取 Home Assistant 中所有或特定域的实体列表，方便 LLM 理解可操作的设备和服务。

安装步骤

克隆仓库:

git clone https://github.com/hekmon8/Homeassistant-server-mcp.git
cd Homeassistant-server-mcp

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

服务器配置

要将 Home Assistant MCP Server 集成到 MCP 客户端（例如 Claude 客户端），您需要在 MCP 客户端的设置文件中添加服务器配置信息。以下是一个配置示例，您需要根据实际情况修改路径和 Home Assistant 的连接信息。

{
  "mcpServers": {
    "homeassistant": {  // 服务器名称，在 MCP 客户端中引用此名称
      "command": "node",  // 启动服务器的命令，这里使用 Node.js 运行
      "args": ["/path/to/homeassistant-server-mcp/build/index.js"], // 服务器启动脚本的路径，请替换为实际路径
      "env": {
        "HA_URL": "http://your-homeassistant-url:8123",  // 您的 Home Assistant 实例的 URL，例如 http://192.168.1.100:8123，请替换为实际地址
        "HA_TOKEN": "your-long-lived-access-token"  // 您的 Home Assistant 长期访问令牌，请替换为实际令牌
      }
    }
  }
}

配置参数说明:

'"homeassistant"': 您为该 MCP 服务器自定义的名称，在 MCP 客户端调用工具时会用到。
'"command": "node"': 指定用于运行服务器的命令，这里假设您已安装 Node.js 运行环境。
'"args": ["/path/to/homeassistant-server-mcp/build/index.js"]': 指向编译后的服务器入口文件 'index.js' 的路径。请务必将 '/path/to/homeassistant-server-mcp' 替换为您克隆仓库后 'homeassistant-server-mcp' 文件夹在您电脑上的实际绝对路径。 例如，如果您的 'homeassistant-server-mcp' 文件夹在用户目录下的 'Documents' 文件夹中，那么路径可能类似于 '/Users/yourusername/Documents/homeassistant-server-mcp/build/index.js' (macOS/Linux) 或 'C:\Users\yourusername\Documents\homeassistant-server-mcp\build\index.js' (Windows)。
'"env"': 环境变量配置，用于服务器连接 Home Assistant 实例：
- '"HA_URL"': Home Assistant 的 API 地址，包括协议和端口。
- '"HA_TOKEN"': Home Assistant 的长期访问令牌，用于API 鉴权。您需要在 Home Assistant 后台生成长期访问令牌并填写在这里。

请注意替换以上配置中的 '/path/to/homeassistant-server-mcp'、 'http://your-homeassistant-url:8123' 和 'your-long-lived-access-token' 为您实际的值。

基本使用方法

配置完成后，在支持 MCP 协议的 LLM 客户端中，您可以使用 'use_mcp_tool' 函数来调用 Home Assistant MCP Server 提供的工具。例如，要获取 'light.living_room' 的状态，您可以使用以下方式：

use_mcp_tool({
  server_name: "homeassistant", //  配置中设置的服务器名称 "homeassistant"
  tool_name: "get_state",      //  要调用的工具名称：获取设备状态
  arguments: {
    entity_id: "light.living_room" //  工具的参数，这里指定要查询的实体 ID
  }
});

更多工具的使用方法，请参考仓库 'README.md' 文件中 "Usage" 部分的示例。

关键词