Home Assistant MCP 服务器

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

特性

• 通过自然语言查询和控制 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）

环境变量

获取长期访问令牌的步骤：

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

使用

作为独立服务器运行

# 标准模式（需要运行中的 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 集成：

1. 编辑您的 Claude Desktop 配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 添加服务器配置：

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

如果您的 Home Assistant 正在运行，请移除 --mock 标志并将 HASS_MOCK 设置为 false。

3. 重启 Claude Desktop

可用工具

服务器提供了多个工具来与 Home Assistant 交互：

• states - 查询实体状态
• lights - 列出灯光
• light - 控制灯光
• service - 调用 Home Assistant 服务
• history - 获取历史实体数据
• services - 列出可用的服务
• config - 获取 Home Assistant 配置
• domains - 列出可用的域
• error_log - 获取 Home Assistant 错误日志
• devices - 获取 Home Assistant 中的所有设备

有关详细用法示例，请参阅 docs/hass-mcp.md。

安全性

此服务器需要具有完全访问权限的 Home Assistant 访问令牌。请考虑以下安全建议：

• 仅在受信任的网络上运行服务器
• 如果远程暴露服务器，请使用 HTTPS
• 保持 .env 文件的安全，不要将其提交到源代码控制中
• 尽可能使用权限受限的令牌

许可证

该项目基于 MIT 许可证 - 详见 LICENSE 文件。