Home Assistant MCP Server

A Model Context Protocol server that turns your Home Assistant instance into a safe workbench for AI agents — built to author and validate configuration and automations, not to control your home.

Point Claude (or any MCP client) at it and the agent can:

• See what exists, live — entities, services, events, areas, devices, labels, state history, logbook.
• Author configuration — create/edit automations, configure the Energy dashboard, manage Zigbee (ZHA) groups, register Lovelace resources, prune HACS repositories, rename entities, reload YAML domains.
• Validate its own work — render Jinja2 templates against live state, run HA's config check, read the error log, and inspect step-by-step execution traces of automations it wrote.
• Never touch your devices — there is deliberately no call_service, no set_state, and no fire_event. The agent writes config; it cannot turn anything on or off.

43 tools, zero install (npx), works with Claude Code, Claude Desktop, Cursor, and any other MCP client.

Example prompts

"Create an automation that turns on the porch light 30 minutes before sunset, but only when someone is home."

"My 'goodnight' automation didn't fire last night. Figure out why."

"Write a template sensor for net grid power and validate it against live state before I put it in my YAML."

"Set up my Energy dashboard: grid import/export from these two sensors, solar from the inverter, and add every smart plug as an individual device."

"Group the three living-room bulbs into one Zigbee group so they dim in sync."

"I uninstalled a HACS card — find and remove the dangling Lovelace resource."

Install

The package is published as @orellbuehler/homeassistant-mcp and runs directly with npx — no clone or build needed:

claude mcp add homeassistant \
  --env HASS_URL=http://homeassistant.local:8123 \
  --env HASS_TOKEN=your-long-lived-access-token \
  -- npx -y @orellbuehler/homeassistant-mcp

See Usage with Claude Code for the equivalent JSON config. For any other MCP client, run the package directly — npx -y @orellbuehler/homeassistant-mcp with HASS_URL and HASS_TOKEN set in the environment. Requires Node.js 20+.

Getting a token

HASS_TOKEN must be a Long-Lived Access Token:

1. In Home Assistant, open your profile (click your username, bottom-left).
2. Go to the Security tab → Long-lived access tokens → Create token.
3. Copy the token (it is shown only once) and treat it like a password.

The token inherits your user's permissions. To limit what the agent can see, create a dedicated HA user with the access you want and generate the token as that user.

Configuration

| Variable | Required | Description | | ------------- | -------- | --------------------------------------------------------------------------------- | | HASS_URL | yes* | Base URL of your instance, e.g. http://homeassistant.local:8123. https works. | | HASS_SERVER | no | Alias for HASS_URL (compatible with hass-cli). Used if HASS_URL is unset. | | HASS_TOKEN | yes | Long-lived access token. |

* Either HASS_URL or HASS_SERVER must be set. The WebSocket URL is derived automatically (http→ws, https→wss, plus /api/websocket).

Usage with Claude Code

Add the server to ~/.claude/settings.json (or a project .mcp.json):

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["-y", "@orellbuehler/homeassistant-mcp"],
      "env": {
        "HASS_URL": "http://homeassistant.local:8123",
        "HASS_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}

If you built from source instead, use "command": "node" with "args": ["/path/to/homeassistant-mcp/dist/index.js"]. Restart Claude Code and the tools are available immediately. Verify with claude mcp list (should show homeassistant ✓ connected) or /mcp inside a session.

Tools

43 tools in 12 groups. REST tools go through the Home Assistant REST API; WebSocket tools use the config registries that are not exposed over REST.

Entities & state (REST)

| Tool | Description | | --------------- | ---------------------------------------------------------------------- | | list_entities | Compact summary of live entities (filter by domain and/or search). | | get_entity | Full state object for one entity, including all attributes. | | list_domains | Distinct entity domains present, with counts. |

Services & events (REST)

| Tool | Description | | --------------- | ----------------------------------------------------------------------------------- | | list_services | Callable services (actions for automations/scripts). Pass domain for full fields. | | list_events | Event types being listened for, with listener counts (for event triggers). |

System & validation (REST)

| Tool | Description | | ----------------- | ------------------------------------------------------------------------------ | | get_config | Running config: version, components, unit system, time zone, etc. | | check_config | Validate the YAML config on the server (/api/config/core/check_config). | | get_error_log | Error log as text (tail to lines, default 100). | | render_template | Render a Jinja2 template against live state — for template sensors/conditions. |

History (REST)

| Tool | Description | | ------------- | ---------------------------------------------------------- | | get_history | State history for one or more entities over a time window. | | get_logbook | Human-readable logbook entries. |

Reload (REST, curated allowlist)

| Tool | Description | | -------- | ------------------------------------------------------------------------------------------ | | reload | Reload a reloadable domain so YAML edits apply without a restart (all, automation, …). |

Automations (REST, /api/config/automation)

| Tool | Description | | ----------------------- | ------------------------------------------------------------------------------ | | get_automation_config | Stored config (triggers/conditions/actions/mode) of one automation. | | upsert_automation | Create a new automation or replace an existing one's config (validated by HA). | | delete_automation | Delete a UI-managed automation. |

All three accept the automation.* entity id (the internal id is resolved automatically) or the internal id itself. Writes require an admin token; HA validates the config, stores it in automations.yaml and reloads automations automatically. upsert_automation replaces the whole config, so edit via get_automation_config → modify → upsert_automation. Only automations with an id (UI-created / automations.yaml) are reachable — automations defined elsewhere in YAML are not. Debug the result with the trace tools below.

Registries (WebSocket)

| Tool | Description | | ------------------------ | ---------------------------------------------------------------------------------------- | | list_registry_entities | ALL registered entities, incl. disabled/unavailable (area, device, status). | | rename_entity | Set an entity's registry name and/or new_entity_id (config edit, no device control). | | set_entity_enabled | Enable/disable entities in the registry (batch, per-entity results). | | list_devices | Devices (id, name, manufacturer, model, area). | | list_areas | Areas (area_id, name, floor). | | list_labels | Labels (label_id, name, color, icon). |

list_entities (REST) shows entities that currently have state; list_registry_entities (WebSocket) shows everything registered, including disabled entities, with area/device grouping. rename_entity writes the registry via config/entity_registry/update (requires an admin token): name overrides the friendly name (null reverts to the integration's original_name) and new_entity_id renames the entity_id within the same domain. set_entity_enabled uses the same command (also admin-only) to set disabled_by to null (enable) or "user" (disable) for a batch of entity_ids; one failure does not abort the rest, and each entity comes back with its own ok/error and resulting disabled_by. Enabling is not instant — HA loads the entity after its config entry reloads (reload_delay, usually 30 seconds) or after a restart when the response sets require_restart.

Energy dashboard (WebSocket)

| Tool | Description | | ------------------------- | ----------------------------------------------------------------------------------- | | get_energy_prefs | Current Energy dashboard preferences (sources + the Individual-devices list). | | save_energy_prefs | Overwrite preferences (read-modify-write; replaces each provided key). | | add_energy_devices | Append entities to Individual devices, deduped, with optional eligibility warnings. | | remove_energy_devices | Remove entities from Individual devices by stat_consumption. | | validate_energy_prefs | Run energy/validate and correlate issues with each entity/source. | | set_energy_grid_source | Set the single grid source (import/export plus optional cost/price stats). | | set_energy_solar_source | Add or update a solar production source (upsert by stat_energy_from). |

The Energy dashboard config lives in .storage/energy and is only reachable over WebSocket (not REST). The write tools (save_energy_prefs, add_/remove_energy_devices, set_energy_*) call energy/save_prefs, which requires an admin token. They are read-modify-write (fetch the current prefs, then save), so editing the Energy dashboard in the HA UI at the same moment can be overwritten — this is fine for the intended single-agent use.

Traces (WebSocket, read-only)

| Tool | Description | | -------------------- | ----------------------------------------------------------------------------------- | | list_traces | Recent execution traces (newest first) for an automation.*/script.* entity. | | get_trace | Full step-by-step trace for one run (config, variables, context, error). | | get_trace_contexts | Map context ids to the trace run that produced them (causality across automations). |

Pass an automation.* or script.* entity id; the trace key is resolved automatically. Use these to debug whether and how an automation you authored actually ran.

ZHA / Zigbee groups (WebSocket)

| Tool | Description | | -------------------------- | ----------------------------------------------------------------------------------- | | list_zha_groups | Existing ZHA groups (group_id, name, members). | | list_zha_groupable | Endpoints that can join a group (ieee + endpoint_id + their entities). | | create_zha_group | Create a group on the coordinator; members by entity_id or {ieee, endpoint_id}. | | add_zha_group_members | Add members to a group. | | remove_zha_group_members | Remove members from a group. | | remove_zha_group | Delete group(s) by id (member devices untouched). |

A ZHA group lives on the Zigbee coordinator and is exposed to HA as one group entity (e.g. a single light.* that drives all members together via Zigbee multicast). This is configuration authoring, not device control — like creating a helper, it changes what entities exist, not their on/off state. The write tools call zha/group/* and require an admin token. Members must be groupable ZHA endpoints (devices that support the Zigbee Groups cluster); create_zha_group / add_zha_group_members accept entity_ids and resolve them to {ieee, endpoint_id} via list_zha_groupable, or you can pass the {ieee, endpoint_id} pairs directly. The HA group entity is created asynchronously, so read its final entity_id from the entity registry afterwards.

Lovelace resources (WebSocket)

| Tool | Description | | -------------------------- | -------------------------------------------------------------------------- | | list_lovelace_resources | Registered dashboard resources (id, type, url), e.g. /hacsfiles/…. | | create_lovelace_resource | Register a JS/CSS URL loaded on every dashboard (defaults to module). | | update_lovelace_resource | Change a resource's url and/or type by id. | | delete_lovelace_resource | Remove a resource by id (e.g. the dangling one left after a HACS removal). |

Resources are the JS/CSS bundles loaded into every dashboard (Settings → Dashboards → Resources). The write tools call lovelace/resources/*, require an admin token, and only work when the resource registry is in storage mode (lovelace: mode: storage); they are disabled if Lovelace is globally in YAML mode. This is config authoring, not device control.

HACS (WebSocket)

| Tool | Description | | ------------------------ | ------------------------------------------------------------------------------- | | list_hacs_repositories | HACS repositories (installed-only by default): id, category, versions, paths. | | remove_hacs_repository | Uninstall a repository by id — deletes its downloaded files and unregisters it. |

list_hacs_repositories maps each repo to id + local_path/file_name, so you can tell which /hacsfiles/… Lovelace resource belongs to a plugin. remove_hacs_repository calls hacs/repository/remove (admin token) and deletes the plugin's files; when HACS manages resources (storage mode) it also drops the plugin's Lovelace resource for you, so verify with list_lovelace_resources and only delete_lovelace_resource one that's left behind. Removing an integration you still reference in YAML will break that config, so check usage first.

Safety boundary

• No device control. There is no generic call_service, no set_state, and no fire_event. The server cannot turn things on/off.
• reload is restricted to a fixed allowlist of *.reload / homeassistant.reload_* services. It restarts reloadable domains (e.g. re-reads automations.yaml) but cannot control devices.
• Automation configs are writable via the /api/config/automation REST API (upsert_automation / delete_automation). This is the server's core purpose — authoring automations — and needs an admin token. Be aware that an automation, once written, runs its actions whenever its triggers fire, so review configs before writing. The server still cannot run services directly: no call_service, set_state, or fire_event.
• Energy dashboard config is writable via energy/save_prefs (the *_energy_* tools). This is configuration authoring — the dashboard's sources and Individual-devices list — not device control, and it needs an admin token. No call_service, set_state, or fire_event is added.
• ZHA groups are writable via zha/group/* (the *_zha_group* tools). Creating/editing a Zigbee group changes which group entities exist (config authoring), not any device's on/off state, and it needs an admin token. Still no call_service, set_state, or fire_event.
• Lovelace resources are writable via lovelace/resources/* (the *_lovelace_resource tools) — which JS/CSS bundles load into dashboards. Config authoring, admin token, storage-mode only.
• HACS repositories are removable via hacs/repository/remove (remove_hacs_repository). This uninstalls a plugin/integration/theme and deletes its files (admin token); there is no install tool (the server never downloads third-party code). Still no call_service, set_state, or fire_event.
• Read tools expose your home's data (entity names, states, areas) to the agent/LLM. Use a scoped HA user if that matters to you.
• Prefer https and a trusted network path to your instance.

Development

npm install
npm run build         # tsc -> dist/
npm test              # vitest run
npm run typecheck     # tsc --noEmit
npm run lint          # eslint src
npm run format:check  # prettier --check .

Run a single test file:

npx vitest run src/__tests__/entities.test.ts

CI / Releasing

• CI (.github/workflows/ci.yml) runs on every push to main and on pull requests: format:check, lint, typecheck (once) and test + build on Node 20 and 22.
• Publish (.github/workflows/publish.yml) runs when a GitHub Release is published. It builds, tests, and publishes to npm using trusted publishing (OIDC) — no NPM_TOKEN secret required, with provenance generated automatically. It skips publishing if that version is already on npm.

One-time setup on npmjs.com: open the package's Settings → Trusted Publisher and add a GitHub Actions publisher for repository OrellBuehler/homeassistant-mcp with workflow publish.yml. If the package doesn't exist on npm yet, do one manual npm publish --access public (after npm login) to create it, then add the trusted publisher for all future releases.

Cut a release:

npm version patch          # bumps package.json + creates a vX.Y.Z tag (use minor/major as needed)
git push --follow-tags
gh release create "v$(node -p "require('./package.json').version")" --generate-notes

License

MIT © Orell Bühler