适合谁
- 希望用自然语言控制智能家居的 Home Assistant 用户
- 喜爱 Claude 等 AI 助手的开发者
- 需要快速排查自动化和实体问题的用户
H
52FMRS · D
Hass-MCP 功能丰富，覆盖实体管理、自动化、历史数据、日志等，token 效率高。但安全风险突出，HTTP 模式需严格保护。适合追求 AI 控制家居的用户，但需谨慎配置权限和网络。
Hass-MCP 是一个模型上下文协议（MCP）服务器，用于将 Home Assistant 与 Claude 和其他大语言模型集成。它允许 AI 助手直接读取设备状态、控制灯光和开关、获取智能家居摘要、排查自动化问题以及搜索实体，并提供简洁的 JSON 响应以节省 token。
工具能力
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
获取实体在指定时间范围内的状态变更历史
get_statistics
获取长期聚合统计（均值/最小值/最大值），适用于超过短期保留期数据
get_statistics_range
获取指定时间范围内的长期统计，适合月度/年度趋势
get_error_log
获取错误日志，支持级别、集成、搜索词和行数过滤
get_entities_by_area
列出特定区域或房间的实体
安装接入
- 准备 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"
}
}
}
}
选型与风险
不适合谁
- 不需要 AI 控制的用户
- 无法管理长期访问令牌或网络配置的用户
- 需要离线或本地封闭环境、不能暴露服务端口的用户（尤其是 HTTP 模式）
所需权限
- 需要 Home Assistant 长期访问令牌（HA_TOKEN）
- 通过 HA_URL 访问 Home Assistant 实例，需要网络可达
- HTTP 模式下需要开放端口，但必须通过代理或 VPN 保护，避免未授权访问
风险与副作用
- 若 HTTP 模式暴露到公网，任何人可控制全部智能设备（如开关灯、解锁门、触发自动化、重启 HA）
- 令牌泄露可能导致完全控制 Home Assistant
- 错误操作可能引发设备异常或自动化误触发
常见排障
- 检查 HA_URL 是否可达，Docker 内可用 host.docker.internal 或实际 IP
- 确认 HA_TOKEN 有效且未过期
- 若 Docker 容器无法访问 HA，尝试添加 --network host 或使用主机 IP
- 查看客户端日志，确认 MCP 服务器是否正常启动
- 若使用自定义 CA 证书，确保通过 SSL_CERT_FILE 指定证书
- HTTP 模式下确保端口绑定和代理配置正确
使用场景
询问当前客厅灯光状态
关闭厨房所有灯
查询主卧温度
列出所有含温度数据的传感器
创建日落时自动开灯的自动化
排查卧室人体传感器自动化不工作的问题
查看 Home Assistant 日志中的错误
获取上月每日用电量
支持客户端
Claude Desktop完整支持
Cursor完整支持
Claude Code完整支持