Home Assistant MCP Server

项目简介

该项目 'home-assistant-mcp-server' 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在桥接 Home Assistant 智能家居系统与支持 MCP 协议的客户端（如 Claude Desktop）。它允许大型语言模型 (LLM) 通过标准化的 MCP 协议，以自然语言的方式查询和控制您的 Home Assistant 设备，实现智能家居的自然语言交互。

主要功能点

Home Assistant 集成: 能够连接和操作 Home Assistant 智能家居平台，实现对智能设备的控制和状态查询。
MCP 协议兼容: 完全兼容 Model Context Protocol，可以与任何 MCP 客户端无缝对接。
自然语言交互: 支持通过自然语言查询和控制 Home Assistant 实体，使得 LLM 可以理解和执行智能家居指令。
丰富的功能工具: 提供状态管理、服务调用、历史记录等多种工具，扩展 LLM 与智能家居的交互能力。
安全认证: 采用 Home Assistant 长期访问令牌进行安全认证，保障智能家居控制的安全性。
多种传输协议: 支持 Stdio 和 SSE 多种传输协议，适应本地进程和远程客户端等不同应用场景。
演示模式: 内置演示模式，无需真实 Home Assistant 环境即可进行测试和功能演示。

安装步骤

本 MCP 服务器可以使用 'bun' 包管理器或从源代码安装。

使用 bun 安装 (推荐):

bun install -g home-assistant-mcp-server

从源代码安装:

git clone https://github.com/oleander/home-assistant-mcp-server.git
cd home-assistant-mcp-server
bun install
bun run build
bun link

服务器配置

MCP 客户端（如 Claude Desktop）需要配置 MCP 服务器的启动命令和必要的环境变量才能连接。以下是 Claude Desktop 的 'claude_desktop_config.json' 配置文件示例，用于配置 'home-assistant-mcp-server'：

{
  "mcpServers": {
    "homeassistant": {
      "command": "home-assistant-mcp-server",
      "env": {
        "HASS_URL": "http://your-home-assistant:8123",
        "HASS_TOKEN": "your_token_here"
      }
    }
  }
}

配置参数说明:

server name: 'homeassistant' - 服务器名称，可以自定义，用于在客户端中标识该服务器连接。
command: 'home-assistant-mcp-server' - MCP 服务器的启动命令。请确保 'home-assistant-mcp-server' 命令在您的系统路径中可用。
env: 环境变量配置，以 JSON 对象形式提供。
- HASS_URL: Home Assistant 实例的 URL 地址，例如 'http://homeassistant.local:8123'。（必填）
- HASS_TOKEN: 用于 Home Assistant 认证的长期访问令牌。请在 Home Assistant 用户配置页面创建并获取。（必填）
- PORT: HTTP 服务器端口号，默认为 '3000'。仅在使用 HTTP/SSE 传输时需要配置。（可选）
- HASS_MOCK: 是否启用模拟数据模式。设置为 '"true"' 时，服务器将使用模拟数据，无需连接到真实的 Home Assistant 实例，默认为 '"false"'。（可选，测试或演示时使用）

获取 Home Assistant 长期访问令牌步骤:

登录您的 Home Assistant 实例。
点击左下角的您的个人资料。
滚动到 长期访问令牌 部分。
点击 创建令牌 并输入一个描述性名称。
复制生成的令牌值（请注意，令牌只会显示一次）。

基本使用方法

配置环境变量: 在运行 'home-assistant-mcp-server' 的目录中创建 '.env' 文件，并根据您的 Home Assistant 环境配置 'HASS_URL' 和 'HASS_TOKEN' 等环境变量。
启动服务器: 在终端中运行 'home-assistant-mcp-server' 命令以启动服务器 (默认使用 HTTP/SSE 传输)。如需使用 Stdio 传输，请运行 'home-assistant-mcp-server --stdio'。
配置 MCP 客户端: 在 MCP 客户端（如 Claude Desktop）中，根据上述 服务器配置 部分的说明，配置服务器连接信息，确保 'command' 和 'env' 参数正确设置。
连接和使用: 在 MCP 客户端中连接到配置的 'homeassistant' 服务器，即可开始通过自然语言与您的 Home Assistant 智能家居系统进行交互。

启动命令示例:

标准模式 (连接真实 Home Assistant):

home-assistant-mcp-server
home-assistant-mcp-server --stdio

演示模式 (使用模拟数据):

home-assistant-mcp-server --mock
home-assistant-mcp-server --stdio --mock

关键词