---
name: Home Assistant API access patterns
description: How to query HA automations, entity registry, history, and other data not available via MCP tools
type: reference
---

The HA MCP tools (`mcp__home-assistant__*`) cover device control, entity states, and live context — but NOT automations, entity registry, history, logbook, or traces.

For those, use the HA APIs directly:

- **REST API** (via curl): `http://192.168.86.36:8123/api/...` with Bearer token from `.mcp.json` (`home-assistant.headers.Authorization`)
  - `GET /api/states` — all entity states (filter by entity_id prefix for automations, etc.)
  - `GET /api/config/automation/config/<id>` — full automation config (triggers, conditions, actions) by numeric ID from entity attributes
  - `GET /api/history/period/<timestamp>?filter_entity_id=...` — historical state changes
  - `GET /api/logbook/<timestamp>?entity=...` — logbook entries

- **WebSocket API** (`ws://192.168.86.36:8123/api/websocket`): needed for entity registry operations
  - `config/entity_registry/remove` — delete stale/duplicate entities
  - `config/entity_registry/list` — full entity registry (very large response)
  - Requires `websockets` Python package (installed on Mac)
  - **IMPORTANT**: Must set `max_size=10*1024*1024` on `websockets.connect()` — the entity registry response exceeds the default 1MB limit
  - **Trace API** (`/api/trace/<entity_id>`): may return non-standard JSON or 404. Wrap in try/except and check raw response before parsing.

- **Auth token**: Available as `$HA_TOKEN` env var (set in settings.local.json). Use `Bearer $HA_TOKEN` in curl, or `os.environ['HA_TOKEN']` in Python.

**How to apply:** When user asks about automations, entity cleanup, or historical data, use these APIs rather than saying the MCP can't do it. Always use these patterns from the main conversation — subagents may not have Bash access.