MCP server for Home Assistant that exposes the REST API and WebSocket registries as tools for AI agents.

It is built to help an agent author and validate Home Assistant configuration and automations — not to control your home. It tells the agent what exists live (entities, services, events, areas, devices), validates the agent's work (render Jinja2 templates, check config, read the error log), can reload reloadable domains after YAML edits, and can configure the Energy dashboard (sources and the Individual-devices list). It deliberately has no tools to turn devices on/off, set states, or fire events.

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+.

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.

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

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.

Entities & state (REST)

Services & events (REST)

System & validation (REST)

History (REST)

Reload (REST, curated allowlist)

Registries (WebSocket)

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.

Energy dashboard (WebSocket)

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)

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)

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.

• 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.
• 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.
• 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.

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 (.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

MIT © Orell Bühler