Hass-MCP

Hass-MCP

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

概述

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

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

截图

功能

• 实体管理：获取状态、控制设备并搜索实体
• 域摘要：获取有关实体类型的概要信息
• 自动化支持：列出并控制自动化
• 引导式对话：使用提示词执行创建自动化等常见任务
• 智能搜索：按名称、类型或状态查找实体
• 实时仪表盘编辑：通过 Home Assistant 的 WebSocket API 读取和编辑 Lovelace 仪表盘（卡片和视图）——更改会立即显示在已打开的浏览器中，并支持自动备份和试运行预览
• 令牌效率：精简的 JSON 响应，最大限度减少令牌使用量

安装

前置条件

• 带有长期访问令牌的 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 并进入 Settings b. 前往 Developer > Edit Config 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. 现在，Claude Desktop 的工具菜单中应会出现 “Hass-MCP” 工具

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

uv/uvx

1. 在系统上安装 uv。

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

   a. 打开 Claude Desktop 并进入 Settings b. 前往 Developer > Edit Config 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. 现在，Claude Desktop 的工具菜单中应会出现 “Hass-MCP” 工具

其他 MCP 客户端

Cursor

1. 前往 Cursor Settings > MCP > Add New MCP Server
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. 点击“Add”保存

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 传输（流式）

对于无法使用 stdio 的部署场景——在 MCP 网关后运行、托管在 Smithery 上、由多个客户端共用一个服务，或通过 LibreChat、OpenWebUI 等基于网络的工具连接——Hass-MCP 支持 MCP 流式 HTTP 传输。服务以无状态模式运行（不使用 Mcp-Session-Id，返回 JSON 响应），适合横向扩展的主机。

注意

HTTP 模式会通过网络开放对 Home Assistant 的完整控制权限。 任何能够访问该端口的人都可以调用任意工具——关闭灯光、解锁门、触发自动化、重启 HA。MCP 规范目前尚未为此服务提供内置的身份验证层。在实现之前，你必须将其置于以下任一防护措施之后：

• 执行基本身份验证或 bearer 令牌验证的反向代理（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——如果确实希望在本地 LAN 上使用未加密流量，请使用 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”类型视图中的分区
• add_view / remove_view / update_view：编辑仪表板的视图
• list_dashboard_backups / restore_dashboard：列出自动创建的保存前备份并回滚到相应版本

Sections 视图： Home Assistant 的现代视图类型（type: sections）会将卡片存储在分区中，而不是单个顶层列表中。对于这类视图，请调用 list_view_sections，并向卡片工具传入 section 参数（索引、标题或栏标题）。如果对 sections 视图编辑卡片时未提供 section，系统会拒绝操作并列出可用分区，而不是悄悄保存一张永远不会显示的卡片。

每个编辑工具都支持 dry_run=true，可预览修改后的配置和变更摘要，而不保存更改。

重要说明：

• 需要管理员令牌。 保存 Lovelace 配置时，长期令牌必须属于管理员用户。
• 仅支持存储模式。 只能编辑由 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 许可证