HA MCP Server

An MCP server that exposes Home Assistant's REST and WebSocket APIs as 182 tools, so an MCP client — Claude Code among others — can drive an instance directly.

Lights, climate, covers, media, alarm and cameras; automations, scripts, scenes, helpers and dashboards; the area, floor, label, device and entity registries; add-ons, HACS, backups and system health; history, logbook, statistics and energy.

A status dashboard shows what the server sees and which tools have been called.

It can also delete things — automations, dashboards, helpers, users. Every tool was exercised against a live instance before release, but treat it as what it is: a broad, powerful interface to your home.

The screenshot is generated by scripts/screenshots.py against a mock of the Home Assistant API, never against a real instance — the dashboard puts the location name in the page title.

Two ways to run it

As a Home Assistant app

The easiest route if you already run Home Assistant: the app reaches it through the Supervisor, so no long-lived token has to be created, and the dashboard is available in the sidebar through ingress.

Repository: driin0/home-assistant-apps. That repository holds only the packaging — the code is here, and it ships the image published from this repository.

As a container

For a Home Assistant instance you do not control, or to run the server elsewhere:

git clone https://github.com/driin0/ha-mcp-server
cd ha-mcp-server
cp .env.sample .env      # fill in HA_URL, HA_TOKEN and MCP_SECRET
docker compose up -d

The image (ghcr.io/driin0/ha-mcp-server) is published multi-architecture (amd64, arm64), so nothing is built locally. To work on the code, replace image: with build: . in compose.yaml.

Variable	Default	Meaning
HA_URL	—	Home Assistant base URL, e.g. http://homeassistant.local:8123
HA_TOKEN	—	a long-lived access token
MCP_SECRET	—	bearer token clients must present
MCP_ALLOW_NO_AUTH	false	start without a secret — only on a trusted network
MCP_PORT / UI_PORT	47821 / 47822	ports on the host
HA_DEFAULT_LANGUAGE	empty	language for conversation tools
HA_ALEXA_KEYWORDS	echo,alexa	media players treated as Alexa devices
HA_REMOTE_PREFIXES	empty	entity prefixes routed as remotes

Connecting a client

{
  "mcpServers": {
    "homeassistant": {
      "type": "http",
      "url": "http://<host>:47821/mcp",
      "headers": { "Authorization": "Bearer <MCP_SECRET>" }
    }
  }
}

Development

pip install -r requirements.txt
HA_URL=… HA_TOKEN=… MCP_ALLOW_NO_AUTH=true python3 server.py

The tools live in tools/, one module per area, and register themselves through tools/_base.py. web.py serves the dashboard; stats.py keeps the call counters behind it.

A note on the base image

The image is built on python:3.13-alpine on purpose, and its Alpine and Python versions must stay aligned with the Home Assistant base image (ghcr.io/home-assistant/base-python:3.13-alpineX.Y). The Home Assistant app copies the compiled packages from this image rather than reinstalling them, and native extensions — pydantic_core, cryptography, rpds, websockets — only load if musl and the Python minor version match. The Dockerfile imports them at build time so a future mismatch fails there, not at first start.

Licence

Copyright (C) 2026 Riccardo Riina (driin0)

Distributed under the GNU Affero General Public License v3.0. See LICENSE.

Trademarks

Home Assistant and its logo are trademarks of the Open Home Foundation. The Model Context Protocol and its mark belong to Anthropic. This project is independent and is not affiliated with, nor endorsed by, either.