Home Assistant MCP

An MCP server that exposes a Home Assistant instance as a tool set, running as a stateful agent on Cloudflare Workers. Point an MCP client (Claude, etc.) at the deployed endpoint and it can read entity states, call services, run scripts and automations, and send commands to phones via the HA companion app — all against your own Home Assistant instance.

The tool surface is built for a model rather than for the REST API: results are scoped to the entities you exposed to your voice assistant, rendered as one compact line per entity grouped by room, and every entity argument accepts a friendly name as readily as an entity_id.

How it works

MCP client ──HTTP/SSE──► Worker (/mcp) ──► HomeAssistantMCP (Durable Object)
                                                    │
                                             EntityCatalog
                                                    │
                                          HomeAssistantClient
                                                    │
                     HA REST API + /api/websocket (long-lived token)

HomeAssistantMCP is a McpAgent hosted on a Durable Object. EntityCatalog sits between the tools and the API: it joins entity states to their area and floor, narrows them to the exposed set, resolves friendly names to entity IDs, and caches everything. HomeAssistantClient underneath is a thin, cache-free wrapper around the HA REST API. Areas, floors and hidden entities have no REST endpoint, so they come from a single /api/template Jinja render.

Only what you exposed

/api/states on a real installation is a wall of firmware-update notices, signal-strength sensors and diagnostic switches. So the server scopes itself to the entities you picked in Settings → Voice assistants → Expose, read over the WebSocket API (homeassistant/expose_entity/list — there is no REST equivalent, and it requires a token belonging to an admin user).

If that list can't be read, the server falls back to Home Assistant's own default-exposure rules — lights, switches, covers, climate, media players and the handful of sensor device classes HA itself exposes by default — and says so in list_areas. A filter narrow enough to match nothing exposed (say domain: "automation") widens automatically, so nothing is unreachable.

Caching

The Durable Object outlives a tool call, so a multi-tool turn costs one request to Home Assistant rather than one per tool: states are cached for 3 seconds and invalidated the moment a service call changes something, while the area registry and the Expose list are cached for 10 minutes.

Related MCP server: hass-mcp

Tools

get_entities returns lines like:

## Kitchen — Ground
light.kitchen_ceiling | Kitchen Ceiling | on | brightness=71%
sensor.kitchen_temp | Kitchen Temperature | 21.4 °C

Anything taking an entity — get_entity_state, call_service's entity_id, activate, get_history — accepts "kitchen ceiling" just as well as light.kitchen_ceiling, and answers an ambiguous name with the candidates rather than a guess.

Setup

npm install

HA_URL is set in wrangler.jsonc under vars — point it at your own Home Assistant instance before deploying. HA_ASSISTANT is optional and names the assistant whose Expose list to use; it defaults to conversation.

HA_TOKEN (a long-lived access token from HA, belonging to an admin user so the Expose list is readable) is read from Cloudflare's Secrets Store, not a plain Wrangler secret. Create it once per account and it's reusable across Workers:

wrangler secrets-store secret create <store-id> \
  --name home-assistant-token --scopes workers --remote

wrangler.jsonc then binds it via secrets_store_secrets:

"secrets_store_secrets": [
  { "binding": "HA_TOKEN", "store_id": "<store-id>", "secret_name": "home-assistant-token" }
]

For local dev, create a local-only secret with the same name (omit --remote) so wrangler dev has something to read.

Development

npm run dev          # wrangler dev
npm test             # vitest run
npm run test:watch   # vitest watch mode
npm run typecheck    # tsc --noEmit

Tests mock fetch — including the WebSocket handshake — so no live Home Assistant instance is required to run them.

Deploy

npm run deploy

Or connect this repository to a Cloudflare Worker for git-based deploys. Either way, the home-assistant-token secret must exist in the account's Secrets Store — it is never stored in the repo.

Stack

• Cloudflare Workers + Durable Objects (SQLite-backed)

• Cloudflare Agents SDK (agents/mcp)

• MCP TypeScript SDK

• TypeScript, Zod for tool input schemas, Vitest