hass-mcp — HiTech Lab 版本

由 HiTech Lab 维护和优化 来源：https://github.com/voska/hass-mcp

Hass-MCP

一个用于将 Home Assistant 与 Claude 及其他 LLM 集成的模型上下文协议（MCP）服务器。

概述

Hass-MCP 让 Claude 等 AI 助手能够直接与你的 Home Assistant 实例交互，从而可以：

• 查询设备和传感器的状态

• 控制灯光、开关和其他实体

• 获取你的智能家居摘要

• 排查自动化和实体问题

• 搜索特定实体

• 为常见任务创建引导式对话

Related MCP server: Hass-MCP

截图

功能特性

• 实体管理：获取状态、控制设备、搜索实体

• 域摘要：获取实体类型的高层信息

• 自动化支持：列出并控制自动化

• 引导式对话：使用提示词完成常见任务，例如创建自动化

• 智能搜索：按名称、类型或状态查找实体

• 实时仪表盘编辑：通过 Home Assistant 的 WebSocket API 读取和编辑 Lovelace 仪表盘（卡片和视图）——更改会立即出现在已打开的浏览器中，并带有自动备份和 dry-run 预览

• Token 效率：精简的 JSON 响应以最小化 Token 使用

安装

前提条件

• 具有 Long-Lived Access Token 的 Home Assistant 实例

• 以下任一方式：

  • Docker（推荐）

  • Python 3.13+ 和 uv

使用 Claude Desktop 进行设置

Docker 安装（推荐）

1. 拉取 Docker 镜像：

   docker pull voska/hass-mcp:latest

2. 将 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

3. “Hass-MCP”工具现在应该会出现在你的 Claude Desktop 工具菜单中

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

uv/uvx

1. 在你的系统上安装 uv。

2. 将 MCP 服务器添加到 Claude Desktop：

   a. 打开 Claude Desktop 并进入设置 b. 导航到开发者 > 编辑配置 c. 将以下配置添加到你的 claude_desktop_config.json 文件中：

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "uvx",
         "args": ["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

3. “Hass-MCP”工具现在应该会出现在你的 Claude Desktop 工具菜单中

其他 MCP 客户端

Cursor

1. 转到 Cursor 设置 > MCP > 添加新的 MCP 服务器

2. 填写表单：

   • 名称：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 实例地址

3. 点击“添加”保存

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 实例地址。

HTTP 传输（Streamable）

对于无法使用 stdio 的部署——例如运行在 MCP 网关之后、托管在 Smithery 上、在多个客户端之间共享一个服务器，或从 LibreChat、OpenWebUI 等基于网络的工具连接——Hass-MCP 支持 MCP streamable HTTP 传输。服务器以无状态模式运行（无 Mcp-Session-Id，JSON 响应），适用于水平扩展的主机。

[!CAUTION] HTTP 模式会将 Home Assistant 的完整控制权暴露到网络上。 任何能访问该端口的人都可以调用任何工具——关闭灯光、解锁门、触发自动化、重启 HA。MCP 规范尚未在此服务器中提供内置的身份验证层。在它提供之前，你必须将其置于以下任一保护之后：

• 执行 basic-auth 或 bearer-token 验证的反向代理（nginx、Caddy、Traefik）

• VPN 或零信任网络（Tailscale、WireGuard、Cloudflare Access）

• 仅绑定 localhost（默认——只有在你清楚自己在做什么时才更改 --host）

在没有身份验证的情况下，不要将 :8000 暴露到公网。

本地运行

使用 uvx：

HA_URL=http://homeassistant.local:8123 \
HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
uvx hass-mcp --http --port 8000

服务器默认绑定 127.0.0.1。只有当你还在其前面配置了身份验证时，才使用 --host 0.0.0.0 覆盖。

在 Docker 中运行

docker run --rm -p 8000:8000 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000

在 Docker 内部必须使用 --host 0.0.0.0，这样端口才能通过网桥访问。如果你只希望从宿主机访问，请将发布端口（-p）绑定到 127.0.0.1:8000:8000，或者在其前面放置反向代理。

端点

MCP 端点位于 /mcp。将你的客户端指向 http://<host>:<port>/mcp。

Smithery / PaaS

除了 MCP_PORT 之外，服务器还遵循 PORT 环境变量（Smithery 的约定）。Smithery 部署需要 --http 模式，并会自动读取 PORT。

自定义 / 私有 CA

如果你的 Home Assistant 实例提供由你自己的 CA（step-ca、smallstep、homelab OpenSSL）签发的证书，hass-mcp 可以在不禁用 TLS 的情况下验证它：

• 本地：将 CA 根证书安装到你的操作系统信任库中（macOS Keychain、Windows Cert Store，或 Linux 上的 update-ca-certificates）。hass-mcp 会通过 truststore 自动获取它。

• 在 Docker 中（或任何沙盒运行时）：将 CA 文件绑定挂载，并将 SSL_CERT_FILE 指向它。

docker run --rm \
  -v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
  -e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
  -e HA_URL=https://homeassistant.example.internal:8123 \
  -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  voska/hass-mcp:latest

设置 SSL_CERT_FILE 后，它始终优先于操作系统信任库。有意不支持 verify=False——如果你确实想要未加密的本地局域网流量，请使用 HA_URL=http://...。

使用示例

以下是一些在 Hass-MCP 设置完成后可以配合 Claude 使用的提示词示例：

• “我客厅灯光的当前状态是什么？”

• “关掉厨房里所有的灯”

• “主卧室的温度是多少？”

• “列出客房里的所有东西”

• “列出我所有包含温度数据的传感器”

• “给我一个我的气候实体的摘要”

• “创建一个在日落时开灯的自动化”

• “帮我排查为什么我的卧室运动传感器自动化不工作”

• “搜索与我的客厅相关的实体”

• “显示 Home Assistant 日志中最后 50 行 ERROR”

• “今天 mqtt 集成一直在失败什么？”

• “显示上个月每天的用电量”

• “上周二前门传感器发生了什么？”

可用工具

Hass-MCP 提供了多个用于与 Home Assistant 交互的工具：

• get_version：获取 Home Assistant 版本

• get_entity：获取特定实体的状态，并支持可选字段过滤

• entity_action：对实体执行操作（打开、关闭、切换）

• list_entities：获取实体列表，并支持可选域过滤和搜索

• search_entities_tool：搜索与查询匹配的实体

• domain_summary_tool：获取某个域的实体摘要

• list_automations：获取所有自动化列表

• call_service_tool：调用任何 Home Assistant 服务

• restart_ha：重启 Home Assistant

• get_history：获取实体的状态历史（最近 N 小时）

• get_history_range：在明确的日期/时间范围内（start_time / end_time，ISO-8601）获取实体的状态变更历史

• get_statistics：获取实体在最近 N 小时内的长期聚合统计信息（每个桶的均值 / 最小值 / 最大值）——适用于早于 recorder 短期保留窗口的数据

• get_statistics_range：相同功能，但针对明确的日期/时间范围——适用于月度 / 年度趋势查询

• get_error_log：获取 Home Assistant 错误日志，并可在服务端应用可选的 level / integration / search_term / lines 过滤器，以免嘈杂的日志撑爆 Claude 的上下文

• get_entities_by_area：列出特定区域 / 房间中的实体

仪表盘（Lovelace）编辑

通过 Home Assistant 的 WebSocket API 读取并实时编辑仪表盘。保存后，更改会立即推送到每个已打开的浏览器——无需重启。

• list_dashboards：列出仪表盘（默认仪表盘以及任何用户仪表盘），每个都带有其 url_path 和 mode（storage / yaml）

• get_dashboard_config：获取仪表盘的完整配置

• set_dashboard_config：替换仪表盘的完整配置（底层操作）

• add_card / update_card / remove_card / move_card：在视图中编辑卡片（视图通过索引或其 path / title 选择）

• list_view_sections：列出“sections”类型视图的各个 section

• add_view / remove_view / update_view：编辑仪表盘的视图

• list_dashboard_backups / restore_dashboard：列出并回滚到自动的保存前备份

Sections 视图： Home Assistant 的现代视图类型（type: sections）将其卡片存储在 sections 中，而不是单个顶层列表中。对于这些视图，请调用 list_view_sections，并将 section 参数（索引、标题或 heading）传递给卡片工具。在没有 section 的情况下对 sections 视图进行卡片编辑会被拒绝，并返回可用 sections 列表——而不是静默保存一张永远不会渲染的卡片。

每个编辑工具都接受 dry_run=true，以便在不保存的情况下预览生成的配置和变更摘要。

重要说明：

• 需要管理员令牌。 保存 Lovelace 配置要求长期令牌属于管理员用户。

• 仅限 storage 模式。 只有 UI 管理的（“storage”）仪表盘才能被编辑。YAML 模式仪表盘会被检测到并以明确消息拒绝——请直接编辑它们的 YAML 文件。

• 整配置写入。 Home Assistant 没有部分编辑 API；每次更改都是对整个仪表盘的读取-修改-写入。高层卡片/视图工具会为你处理这一点。

• 自动备份。 每次写入前，当前配置都会保存到 HASS_MCP_BACKUP_DIR（默认 ~/.hass-mcp/dashboard-backups/）。在 Docker 中运行时，请在该路径挂载一个卷，否则容器重建时备份会丢失。

引导式对话的提示词

Hass-MCP 包含多个用于引导式对话的提示词：

• create_automation：基于触发器类型创建 Home Assistant 自动化的指南

• debug_automation：针对无法正常工作的自动化的故障排除帮助

• troubleshoot_entity：诊断实体问题

• routine_optimizer：分析使用模式并根据实际行为建议优化例程

• automation_health_check：审查所有自动化，查找冲突、冗余或改进机会

• entity_naming_consistency：审计实体名称并建议标准化改进

• dashboard_layout_generator：根据用户偏好和使用模式创建优化的仪表板

可用资源

Hass-MCP 提供以下资源端点：

• hass://entities/{entity_id}：获取特定实体的状态

• hass://entities/{entity_id}/detailed：获取具有所有属性的实体的详细信息

• hass://entities：列出按域分组的全部 Home Assistant 实体

• hass://entities/domain/{domain}：获取特定域的实体列表

• hass://search/{query}/{limit}：使用自定义结果限制搜索匹配查询的实体

开发

运行测试

uv run pytest tests/

许可证

MIT 许可证