MCP 服务器

Hass-MCP

一个模型上下文协议服务器，使像 Claude 这样的人工智能助手能够直接与 Home Assistant 交互，从而允许它们查询设备状态、控制智能家居实体以及执行自动化任务。

README

Hass-MCP

一个用于 Home Assistant 集成 Claude 和其他 LLM 的模型上下文协议 (MCP) 服务器。

概述

Hass-MCP 使像 Claude 这样的 AI 助手能够直接与您的 Home Assistant 实例交互，从而允许它们：

查询设备和传感器的状态
控制灯、开关和其他实体
获取智能家居的摘要
排除自动化和实体故障
搜索特定实体
为常见任务创建引导式对话

截图

功能

实体管理: 获取状态、控制设备和搜索实体
域摘要: 获取有关实体类型的高级信息
自动化支持: 列出和控制自动化
引导式对话: 使用提示来完成创建自动化等常见任务
智能搜索: 按名称、类型或状态查找实体
Token 效率: 精简的 JSON 响应，以最大限度地减少 token 使用量

安装

前提条件

具有长期访问令牌的 Home Assistant 实例
以下之一：
- Docker（推荐）
- Python 3.13+ 和 uv

使用 Claude Desktop 设置

Docker 安装（推荐）

拉取 Docker 镜像：
```
docker pull voska/hass-mcp:latest
```
将 MCP 服务器添加到 Claude Desktop：

a. 打开 Claude Desktop 并转到设置 b. 导航到开发者 > 编辑配置 c. 将以下配置添加到您的 claude_desktop_config.json 文件：
```
{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HA_URL",
        "-e",
        "HA_TOKEN",
        "voska/hass-mcp"
      ],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}
```
d. 将 YOUR_LONG_LIVED_TOKEN 替换为您实际的 Home Assistant 长期访问令牌 e. 更新 HA_URL：
- 如果在同一台机器上运行 Home Assistant：使用 http://host.docker.internal:8123（Mac/Windows 上的 Docker Desktop）
- 如果在另一台机器上运行 Home Assistant：使用实际的 IP 或主机名
f. 保存文件并重启 Claude Desktop
“Hass-MCP” 工具现在应该出现在您的 Claude Desktop 工具菜单中

注意: 如果您在同一台机器上的 Docker 中运行 Home Assistant，您可能需要将 --network host 添加到 Docker args 中，以便容器访问 Home Assistant。或者，使用您机器的 IP 地址而不是 host.docker.internal。

其他 MCP 客户端

Cursor

转到 Cursor 设置 > MCP > 添加新的 MCP 服务器
填写表格：
- 名称：Hass-MCP
- 类型：command
- 命令：
```
docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
```
- 将 YOUR_LONG_LIVED_TOKEN 替换为您实际的 Home Assistant 令牌
- 更新 HA_URL 以匹配您的 Home Assistant 实例地址
点击“添加”以保存

Claude Code (CLI)

要与 Claude Code CLI 一起使用，您可以使用 mcp add 命令直接添加 MCP 服务器：

使用 Docker（推荐）：

claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

将 YOUR_LONG_LIVED_TOKEN 替换为您实际的 Home Assistant 令牌，并更新 HA_URL 以匹配您的 Home Assistant 实例地址。