使用说明

项目简介

hekmon8_Homeassistant-server-mcp 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在桥接大型语言模型 (LLM) 与 Home Assistant 智能家居平台。通过此 MCP 服务器，LLM 应用可以调用预设的工具来查询和控制您的 Home Assistant 设备，例如获取设备状态、开关灯、触发自动化场景等。这为智能家居的自然语言控制和自动化提供了强大的后端支持。

主要功能点

获取设备状态: 查询 Home Assistant 中指定实体的当前状态信息。
控制设备状态: 控制 Home Assistant 中实体的状态，例如打开或关闭灯、开关等。
触发自动化: 触发预先配置在 Home Assistant 中的自动化场景。
列出实体: 获取 Home Assistant 中所有可用的实体列表，并支持按域进行过滤。

安装步骤

克隆仓库: 将仓库代码克隆到本地：

git clone https://github.com/MCP-Mirror/hekmon8_Homeassistant-server-mcp.git
cd hekmon8_Homeassistant-server-mcp

安装依赖: 安装项目所需的 npm 依赖包：
```
npm install
```
构建项目: 构建 TypeScript 项目：
```
npm run build
```

服务器配置

要将此 MCP 服务器配置到 MCP 客户端（例如 Claude 客户端），您需要在客户端的 MCP 设置文件中添加以下 JSON 配置。通常，该文件位于 '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json' (VSCode 插件 Claude 的默认配置路径)。

{
  "mcpServers": {
    "homeassistant": {  // 服务器名称，可以自定义，客户端通过此名称引用
      "command": "node",  // 启动服务器的命令，这里使用 node 运行 JavaScript 文件
      "args": ["/path/to/homeassistant-mcp/homeassistant-server/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 长期访问令牌，用于服务器鉴权，请替换为实际令牌
      }
    }
  }
}

请务必替换以下占位符：

'/path/to/homeassistant-mcp/homeassistant-server/build/index.js'：替换为 'homeassistant-server-mcp' 项目在您本地的实际路径。
'http://your-homeassistant-url:8123'：替换为您的 Home Assistant 实例的 URL 地址。
'your-long-lived-access-token'：替换为您在 Home Assistant 中生成的长期访问令牌。

基本使用方法

配置完成后，在 MCP 客户端中，您可以使用 'use_mcp_tool' 函数来调用 Home Assistant MCP 服务器提供的工具。以下是一些示例：

获取设备状态:

use_mcp_tool({
  server_name: "homeassistant", //  配置中定义的服务器名称
  tool_name: "get_state",
  arguments: {
    entity_id: "light.living_room" // Home Assistant 实体 ID
  }
});

切换设备状态:

use_mcp_tool({
  server_name: "homeassistant", //  配置中定义的服务器名称
  tool_name: "toggle_entity",
  arguments: {
    entity_id: "switch.bedroom", // Home Assistant 实体 ID
    state: "on"  //  目标状态，"on" 或 "off"
  }
});

触发自动化:

use_mcp_tool({
  server_name: "homeassistant", //  配置中定义的服务器名称
  tool_name: "trigger_automation",
  arguments: {
    automation_id: "automation.morning_routine" // Home Assistant 自动化 ID
  }
});

列出实体:

use_mcp_tool({
  server_name: "homeassistant", //  配置中定义的服务器名称
  tool_name: "list_entities",
  arguments: {
    domain: "light"  // 可选，实体域过滤器，例如 "light", "switch", "automation"
  }
});

请根据您的 Home Assistant 实例配置和需要控制的设备，调整 'entity_id'、'automation_id' 和 'state' 等参数。

关键词