← 返回目录

Hass MCP Server

社区

让 Claude 等 LLM 控制与查询 Home Assistant 的 MCP 服务器

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 其他第 131 / 230
Stars: ★ 344 非常热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Docker · Python 3.13+
凭据: 需要 API Key / 凭据
许可证: MIT
最近提交: 1 天前
工具数: 15

52FMRS · D

Hass-MCP 功能丰富，覆盖实体管理、自动化、历史数据、日志等，token 效率高。但安全风险突出，HTTP 模式需严格保护。适合追求 AI 控制家居的用户，但需谨慎配置权限和网络。

最强项 · 安装易用性 14/20 最弱项 · 可靠性 7/20

可靠性

7/20

安全与权限

10/20

维护活跃度

7/20

文档质量

14/20

安装易用性

14/20

查看各项评分依据

可靠性 7/20: 本次仅依据 README 与仓库元数据，未提供源码或已缓存的 server manifest，也没有可查验的 CI 工作流或测试文件。README 声称提供大量工具、提示词和资源，但无法核实工具列表是否与真实行为一致，边界条件和错误处理缺少证据，因此按保守原则低于 10 分。
安全与权限 10/20: 凭据通过 HA_URL 和 HA_TOKEN 环境变量传入，示例中未出现真实令牌；但 restart_ha、call_service_tool、entity_action 等高风险操作在文档中没有显示确认机制或最小权限控制，HTTP 模式无内置认证，仅建议在外部自行加反向代理/VPN。README 明确警告了风险并拒绝支持 verify=False，未触犯红线，因此给 10 分。
维护活跃度 7/20: 仓库有 MIT 许可证且未归档，但证据中没有提交历史、版本发布、依赖更新记录或安全响应渠道；星标数和问题数仅作发现信号，不能作为维护活跃度加分项，因此只能给中等偏下的 7 分。
文档质量 14/20: README 覆盖面较好：包含 Docker 与 uvx 安装、Claude Desktop/Cursor/Claude Code 配置、HTTP 传输、自定义 CA、大量使用示例、工具/提示词/资源列表及安全注意事项。但缺少逐工具的参数参考、故障排查指南以及限额/成本说明，因此给 14 分。
安装易用性 14/20: 从 README 看，设置路径清晰：Docker 和 uvx 两种方式均提供了可直接粘贴的 Claude Desktop 配置，Cursor 与 Claude Code 也有具体步骤，HTTP 模式有启动命令与端口说明。但由于静态评审没有 CI 或可执行验证，按校准规则 setup 最高不超过 15 分，本项给 14 分。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络修改第三方账户数据

适合谁

希望用自然语言控制智能家居的 Home Assistant 用户
喜爱 Claude 等 AI 助手的开发者
需要快速排查自动化和实体问题的用户

不适合谁

不需要 AI 控制的用户
无法管理长期访问令牌或网络配置的用户
需要离线或本地封闭环境、不能暴露服务端口的用户（尤其是 HTTP 模式）

所需权限

需要 Home Assistant 长期访问令牌（HA_TOKEN）
通过 HA_URL 访问 Home Assistant 实例，需要网络可达
HTTP 模式下需要开放端口，但必须通过代理或 VPN 保护，避免未授权访问

风险与副作用

若 HTTP 模式暴露到公网，任何人可控制全部智能设备（如开关灯、解锁门、触发自动化、重启 HA）
令牌泄露可能导致完全控制 Home Assistant
错误操作可能引发设备异常或自动化误触发

安装接入

准备工作

运行环境：Docker · Python 3.13+

HA_URL 必填 Home Assistant 实例的地址（如 http://homeassistant.local:8123），按你的部署修改。

HA_TOKEN 必填密钥 Home Assistant 的长期访问令牌（Long-Lived Access Token），在 HA 用户安全设置中创建。

其他可选配置项（4 个）

SSL_CERT_FILE 可选自定义 CA 证书文件路径，用于校验自签名证书的 HA 实例，设置后优先于系统信任库。

HASS_MCP_BACKUP_DIR 可选仪表盘编辑前自动备份的保存目录，默认 ~/.hass-mcp/dashboard-backups/，Docker 运行时需挂载卷。

PORT 可选 HTTP 模式监听端口，兼容 Smithery 的约定，会自动读取。

MCP_PORT 可选 HTTP 模式监听端口的另一可选环境变量。

准备 Home Assistant 实例和长期访问令牌。
使用 Docker 或 uv 安装。
将 MCP 服务器配置添加到 Claude Desktop（或 Cursor、Claude Code）。
设置环境变量 HA_URL 和 HA_TOKEN。
重启客户端。

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"
      }
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "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"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

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

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

配置完成后重启 Claude Desktop，工具列表中应出现 Hass-MCP 的工具（如 get_version、list_entities），让 AI 调用 get_version 返回你的 Home Assistant 版本即说明连接成功。

常见排障

检查 HA_URL 是否可达，Docker 内可用 host.docker.internal 或实际 IP
确认 HA_TOKEN 有效且未过期
若 Docker 容器无法访问 HA，尝试添加 --network host 或使用主机 IP
查看客户端日志，确认 MCP 服务器是否正常启动
若使用自定义 CA 证书，确保通过 SSL_CERT_FILE 指定证书
HTTP 模式下确保端口绑定和代理配置正确

试试这样问

连接成功后，可以直接对 AI 助手这样说：

厨房的灯都关掉
主卧现在的温度是多少？
显示客厅所有传感器，并按温度筛选
帮我排查为什么卧室人体传感器自动化没生效

工具能力 15

get_version 只读

获取 Home Assistant 版本号

get_entity 只读

获取特定实体的状态，支持字段过滤

entity_action 写入

对实体执行操作（如开启、关闭、切换）

list_entities 只读

列出实体，可按域过滤和搜索

search_entities_tool 只读

搜索匹配查询的实体

domain_summary_tool 只读

获取某个域的实体摘要

list_automations 只读

列出所有自动化

call_service_tool 写入

调用任何 Home Assistant 服务

展开其余 7 个工具

restart_ha 破坏性

重启 Home Assistant

get_history 只读

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

get_history_range 只读

获取实体在指定时间范围内的状态变更历史

get_statistics 只读

获取长期聚合统计（均值/最小值/最大值），适用于超过短期保留期数据

get_statistics_range 只读

获取指定时间范围内的长期统计，适合月度/年度趋势

get_error_log 只读

获取错误日志，支持级别、集成、搜索词和行数过滤

get_entities_by_area 只读

列出特定区域或房间的实体

使用场景

询问当前客厅灯光状态

关闭厨房所有灯

查询主卧温度

列出所有含温度数据的传感器

创建日落时自动开灯的自动化

排查卧室人体传感器自动化不工作的问题

查看 Home Assistant 日志中的错误

获取上月每日用电量

支持客户端

Claude Desktop

Cursor

Claude Code

依据项目文档列出，未经本站实测。

详细介绍

Hass-MCP 是一个模型上下文协议（MCP）服务器，用于将 Home Assistant 与 Claude 和其他大语言模型集成。它允许 AI 助手直接读取设备状态、控制灯光和开关、获取智能家居摘要、排查自动化问题以及搜索实体，并提供简洁的 JSON 响应以节省 token。