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.

How it works

MCP client ──HTTP/SSE──► Worker (/mcp) ──► HomeAssistantMCP (Durable Object)
                                                    │
                                          HomeAssistantClient
                                                    │
                                      Home Assistant REST API (Bearer auth)

HomeAssistantMCP is a McpAgent hosted on a Durable Object; each tool call goes through HomeAssistantClient, a thin wrapper around the HA REST API that handles auth, path-safe entity IDs, and error normalization. Areas have no dedicated REST endpoint in HA, so listAreas / getEntitiesByArea go through /api/template with a small Jinja template instead.

Related MCP server: hass-mcp

Tools

Setup

npm install

HA_URL is set in wrangler.jsonc under vars — point it at your own Home Assistant instance before deploying.

HA_TOKEN (a long-lived access token from HA) 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

Tests cover HomeAssistantClient by mocking fetch — 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