/ 目录 / 演练场 / Home Assistant MCP
● 社区 homeassistant-ai 🔑 需要你的密钥

Home Assistant MCP

作者 homeassistant-ai · homeassistant-ai/ha-mcp

用语言控制你的家。87 个工具覆盖设备控制、自动化、仪表盘、能源、历史记录——Claude 成为你的 Home Assistant 高级用户。

ha-mcp 将 Home Assistant 的 REST 和 WebSocket API 封装为 MCP 工具。除了控制灯光开关,它还能编写自动化规则、编辑仪表盘、查询历史/统计数据、管理 HACS 插件、浏览实体注册表——让 Claude 既能诊断,又能重塑你的智能家居配置。

为什么要用

核心特性

实时演示

实际使用效果

ha-mcp.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "ha-mcp": {
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "ha-mcp",
      "command": "uvx",
      "args": [
        "ha-mcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "ha-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "ha-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add ha-mcp -- uvx ha-mcp

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Home Assistant MCP

无需记忆实体 ID,用自然语言控制设备

👤 任何已配置好 Home Assistant 的用户 ⏱ ~5 min beginner

何时使用: 你知道想要什么(「把厨房灯调到 30%」)但不记得确切的 entity_id。

前置条件
  • Home Assistant 长期访问 Token — 个人资料 → 安全 → 创建 Token;保存为 HA_TOKEN 环境变量
  • 已设置 HA_URL — 设置 HA_URL=http://homeassistant.local:8123(或你的实际 URL)
步骤
  1. 查找实体
    Use ha-mcp. Find entities matching 'kitchen light'. Show entity_id, area, and current state.✓ 已复制
    → 1–3 个候选实体及其当前状态
  2. 执行变更
    Set kitchen ceiling lights to 30% brightness, warm white.✓ 已复制
    → 服务调用成功;状态已确认

结果: 按意图控制设备,无需死记硬背。

注意事项
  • 多个实体匹配——切换到了错误的那个 — 批量操作前始终确认 entity_id 列表;使用区域过滤器

根据自然语言描述编写复杂自动化规则

👤 不想写 YAML 的 HA 用户 ⏱ ~15 min intermediate

何时使用: 你想要「如果我离家、日落后且猫粮桶空了,发送通知」——但不想写 YAML。

步骤
  1. 描述意图
    Use ha-mcp. List my person tracker, sun, and cat feeder entities so we can wire an automation.✓ 已复制
    → 相关实体及状态结构
  2. 生成 YAML
    Create automation 'cat-feeder-sundown-alert' with that logic. Don't deploy yet — show me the YAML.✓ 已复制
    → 对话中显示有效的 HA 自动化 YAML
  3. 部署 + 追踪
    Deploy it. Then trigger it manually and show the trace so I can verify the conditions fired.✓ 已复制
    → 自动化出现在 UI 中;追踪记录显示预期分支触发

结果: 自动化正常运行,无需手工编辑 /config/automations.yaml。

注意事项
  • 自动化已部署但从未触发——实体名称拼写错误 — 使用追踪工具;验证 entity_id 是否完全匹配

利用历史记录和统计数据排查电量异常

👤 使用 HA 能源仪表盘的智能家居用户 ⏱ ~25 min intermediate

何时使用: 电费账单突然上涨,你想知道是什么变了。

步骤
  1. 拉取总量
    Use ha-mcp. Compare total kWh per circuit for last 30 days vs the prior 30. Flag deltas >20%.✓ 已复制
    → 按回路分列的表格,异常偏差已高亮显示
  2. 深入排查最差回路
    For the worst-offending circuit, plot hourly usage for the last 7 days and identify the new pattern.✓ 已复制
    → 每小时用量曲线 + 对异常的语言描述
  3. 定位罪魁祸首设备
    Which entity on that circuit changed behavior? Cross-reference automations that touch it.✓ 已复制
    → 具体设备 + 关联自动化已定位

结果: 得到「电动车充电器启用了新计划」这样的具体答案,而非模糊猜测。

注意事项
  • 统计数据质量受限于传感器覆盖范围 — 承认数据盲区;建议补装监测设备的位置

设置「度假模式」,一键控制灯光、门锁、窗帘和通知

👤 即将出门旅行的用户 ⏱ ~30 min intermediate

何时使用: 一小时后就要出发,你想同时开启有人在家的模拟效果和离家行为模式。

步骤
  1. 盘点受影响实体
    Use ha-mcp. List lights in living areas, all door locks, all blinds. Note which are HA-controllable.✓ 已复制
    → 按类别整理的实体列表,附可控性标注
  2. 创建脚本
    Create a script 'vacation_mode_on' that arms locks, randomizes evening lights 18:30–22:30, sets blinds to 50%, and pauses cleaning automations.✓ 已复制
    → 脚本已保存到 HA;手动运行成功
  3. 添加触发器
    Bind it to an input_boolean 'vacation_mode' so I can toggle from the dashboard.✓ 已复制
    → 仪表盘上有切换开关;拨动即执行脚本

结果: 一键开启度假模式;离家时仪表盘已就绪。

注意事项
  • 家里有人时自动上锁 — 添加人员在家检测;有人在家时绝不上锁

组合

与其他 MCP 搭配,撬动十倍杠杆

ha-mcp + filesystem

将 automations.yaml 和 scripts.yaml 备份到 git

Export all automations and scripts via ha-mcp, write to ./ha-config/, commit.✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
search_entities query: str, area?, domain? 几乎每个流程的第一步——找到 entity_id 1 HA API call
call_service domain, service, target, data 应用任何设备或场景变更 1 API call
create_automation yaml_or_object 以编程方式创建自动化规则 1 API call
get_history entity_id, start, end 拉取状态历史用于分析 1 API call
get_statistics statistic_id, period (5min|hour|day|month) 长期聚合数据(能源、气候) 1 API call
trace_automation automation_id, run_id? 调试自动化为何触发或未触发 1 API call

成本与限制

运行它的成本

API 配额
无硬性限额——REST API 为本地调用
每次调用 Token 数
不定;未过滤的实体注册表可能非常庞大
费用
免费(开源)
提示
始终使用带过滤条件的 search_entities——全量注册表转储会消耗大量 token

安全

权限、密钥、影响范围

最小权限: Long-Lived Access Token (full HA scope)
凭据存储: HA_TOKEN 环境变量
数据出站: 仅发往你的 HA 实例 URL——理想情况下保持在本地网络内
切勿授予: 不要将 HA token 提供给任何你不信任的云端 LLM——这涉及物理访问控制(门锁、车库)

故障排查

常见错误与修复

无法连接到 HA

确认 HA_URL 在 MCP 运行的位置可访问;如果在反向代理后面,检查 trusted_proxies 配置

验证: curl $HA_URL/api/ -H 'Authorization: Bearer $HA_TOKEN'
401 未授权

Token 已过期或被撤销——在个人资料中生成新的长期 token

服务调用返回 400

服务签名不匹配——使用开发者工具面板验证 schema,然后重试

自动化已部署但不触发

使用 trace_automation 查看哪个条件失败;常见原因:entity_id 拼写错误或日出/日落条件时区设置有误

替代方案

Home Assistant MCP 对比其他方案

替代方案何时用它替代权衡
Home Assistant native voice assistants (Piper/Whisper)你希望在不经过云端 LLM 的情况下实现语音控制自然语言灵活性较低;配置更复杂
ha-mcp-server (legacy/forks)你的分叉版本有此版本没有的功能覆盖面较小;本版本有 87 个工具且持续维护

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills