zkl2333 Home Assistant Skill
通过 Home Assistant 内置 MCP Server 控制智能家居设备。支持灯光、空调、风扇、开关、传感器查询等。
前置条件
Home Assistant 2025.2+ 内置 MCP Server，需先在 HA 中启用： 设置 → 设备与服务 → 添加集成 → 搜索 "Model Context Protocol Server"
在你的 mcporter.json 里加入（合并到 mcpServers 下）：
"home-assistant": {
"baseUrl": "http://<HA_IP>:8123/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_HA_LONG_LIVED_TOKEN",
"Accept": "application/json, text/event-stream"
}
}
Long-Lived Token：HA 用户头像 → 安全 → 长期访问令牌 → 创建令牌
常用工具
查询设备状态（REST API 直接查）
MCP 工具不支持直接列出传感器，用 REST API：
TOKEN="YOUR_TOKEN"
HA="http://HA_IP:8123"
# 查温湿度传感器
curl -sf -H "Authorization: Bearer $TOKEN" "$HA/api/states" | python3 -c "
import json,sys
for s in json.load(sys.stdin):
u=s.get('attributes',{}).get('unit_of_measurement','')
if u in ['°C','%']:
print(s['attributes'].get('friendly_name',''), s['state']+u)
"
# 查指定实体
curl -sf -H "Authorization: Bearer $TOKEN" "$HA/api/states/climate.xxx"
开关设备
# 开（推荐用 REST API 指定 entity_id）
curl -sf -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"entity_id": "climate.xxx"}' "$HA/api/services/climate/turn_on"
# 关
curl -sf -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"entity_id": "climate.xxx"}' "$HA/api/services/climate/turn_off"
MCP 工具（通过 mcporter call）
# 开设备（按名称/区域）
mcporter call home-assistant.HassTurnOn name="卧室空调"
mcporter call home-assistant.HassTurnOn area="客厅" domain='["light"]'
# 关设备
mcporter call home-assistant.HassTurnOff name="卧室空调"
# 调灯光亮度/颜色
mcporter call home-assistant.HassLightSet name="客厅灯" color="warm white"
# 设置空调目标温度
mcporter call home-assistant.HassClimateSetTemperature name="卧室空调" temperature=26
# 设置风扇速度（百分比）
mcporter call home-assistant.HassFanSetSpeed name="风扇" percentage=50
常见 Domain 对照
| Domain | 设备类型 |
|---|---|
climate |
空调、暖气 |
light |
灯光 |
switch |
开关、插座 |
fan |
风扇 |
media_player |
音响、电视 |
sensor |
温湿度、传感器 |
humidifier |
加湿器 |
water_heater |
热水器 |
查找 entity_id
MCP 工具按名称匹配时，不一定精准。推荐先用 REST API 查出准确的 entity_id，再操作：
curl -sf -H "Authorization: Bearer $TOKEN" "$HA/api/states" | python3 -c "
import json,sys
for s in json.load(sys.stdin):
if 'climate' in s['entity_id']:
print(s['entity_id'], '|', s['attributes'].get('friendly_name',''), '|', s['state'])
"
使用建议
- 查询类：优先用 REST API
/api/states，数据准确 - 控制类：MCP 工具（
HassTurnOn/Off）按名称匹配，简单场景够用；复杂场景（多设备、精确 entity_id）用 REST API - 心跳集成：可在心跳中查室温/湿度，过冷/过热主动提醒