Home Assistant MCP Server

Home Assistant MCP 服务

一个用于与 Home Assistant 集成的 Model Context Protocol (MCP) 服务，让大模型能够控制和查询你的智能家居。

功能

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

安装

# Install globally using bun
bun install -g home-assistant-mcp-server

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

配置

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

# Required configurations
HASS_URL=http://your-home-assistant:8123  # URL to your Home Assistant instance
HASS_TOKEN=your_long_lived_access_token   # Long-lived access token for authentication

# Optional configurations
PORT=3000                # Port for the HTTP server (default: 3000)
HASS_MOCK=false          # Enable mock data mode when Home Assistant is unavailable (default: 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 连接的情况下进行测试

获取长期访问令牌：

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

用法

作为独立服务运行

# Standard mode (requires a running Home Assistant instance)
home-assistant-mcp-server                # Start with HTTP/SSE transport
home-assistant-mcp-server --stdio        # Start with stdio transport for direct process communication

# Demo mode (with mock data when Home Assistant is unavailable)
home-assistant-mcp-server --mock         # Start with HTTP/SSE transport and mock data
home-assistant-mcp-server --stdio --mock # Start with stdio transport and mock data

与 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 文件。