MCP 服务器

Home Assistant MCP Server

一个模型上下文协议服务器，允许大型语言模型通过自然语言交互来控制和查询 Home Assistant 智能家居系统。

README

Home Assistant MCP 服务器

一个用于与 Home Assistant 集成的模型上下文协议 (MCP) 服务器，允许 LLM 控制和查询您的智能家居。

特性

通过自然语言查询和控制 Home Assistant 实体
适用于任何 MCP 兼容的客户端（如 Claude Desktop）
提供状态管理、服务调用、历史记录等工具
使用 Home Assistant 长期访问令牌进行安全身份验证
多种传输选项（用于本地进程的 stdio，用于远程客户端的 SSE）
在 Home Assistant 不可用时，提供带有模拟数据的演示模式，用于测试和演示

安装

# 使用 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

配置

在当前目录中创建一个 .env 文件，包含以下变量：

# 必需的配置
HASS_URL=http://your-home-assistant:8123  # Home Assistant 实例的 URL
HASS_TOKEN=your_long_lived_access_token   # 用于身份验证的长期访问令牌

# 可选配置
PORT=3000                # HTTP 服务器的端口（默认：3000）
HASS_MOCK=false          # 在 Home Assistant 不可用时启用模拟数据模式（默认：false）

环境变量

变量	是否必需	默认值	描述
`HASS_URL`	是	-	Home Assistant 实例的 URL（例如，http://homeassistant.local:8123）
`HASS_TOKEN`	是	-	用于与 Home Assistant 进行身份验证的长期访问令牌
`PORT`	否	3000	使用 HTTP/SSE 传输时，HTTP 服务器的端口号
`HASS_MOCK`	否	false	设置为 "true" 时，启用模拟数据模式，以便在没有 Home Assistant 连接的情况下进行测试

要获取长期访问令牌：

登录到您的 Home Assistant 实例
点击您的个人资料（左下角）
向下滚动到“长期访问令牌”
创建一个具有描述性名称的新令牌
复制令牌值（您不会再次看到它）

用法

作为独立服务器运行

# 标准模式（需要运行 Home Assistant 实例）
home-assistant-mcp-server                # 使用 HTTP/SSE 传输启动
home-assistant-mcp-server --stdio        # 使用 stdio 传输启动，用于直接进程通信

# 演示模式（在 Home Assistant 不可用时使用模拟数据）
home-assistant-mcp-server --mock         # 使用 HTTP/SSE 传输和模拟数据启动
home-assistant-mcp-server --stdio --mock # 使用 stdio 传输和模拟数据启动

与 Claude Desktop 集成

要与 Claude Desktop 一起使用：

编辑您的 Claude Desktop 配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
添加服务器配置：

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