voska/hass-mcp: A Home Assistant MCP Server for Claude and Other LLMs

What Hass-MCP Actually Solves

Home Assistant already has an HTTP API and a WebSocket API. The friction is that an LLM does not know your entity IDs, does not know which domain a device lives in, and will happily hallucinate a service call. Hass-MCP sits between the model and that API as a Model Context Protocol server, exposing a fixed set of tools: query device and sensor state, control lights and switches, list and control automations, search entities by name, type or state, and produce domain-level summaries. The README also lists prompts for guided conversations, such as creating an automation.

The audience is narrow and specific. You need a running Home Assistant instance with a long-lived access token, plus an MCP-capable client. The README documents Claude Desktop, Cursor and the Claude Code CLI. It also documents a streamable HTTP transport for deployments that cannot use stdio, naming MCP gateways, Smithery hosting, and network-based tools such as LibreChat or OpenWebUI. If you are not already a Home Assistant user, there is nothing here for you.

How the Server Talks to Home Assistant

The dependency list in pyproject.toml is the clearest description of the architecture. It requires the mcp package with the cli extra, httpx, truststore and websockets. That is a small surface: HTTP calls for the REST side, a WebSocket client for the parts that need it, and truststore so TLS verification uses the system certificate store.

Two environment variables carry the whole configuration. HA_URL points at the instance, defaulting in the example to http://homeassistant.local:8123, and HA_TOKEN holds a long-lived access token. The package declares requires-python >=3.13 and exposes a console script named hass-mcp mapped to app.run:main, so the same entry point serves both the stdio and HTTP modes.

The most interesting mechanism is dashboard editing. The README describes reading and editing Lovelace dashboards, cards and views, over Home Assistant's WebSocket API, with changes appearing instantly in open browsers, automatic backups, and a dry-run preview. That is a different class of operation from toggling a light: it mutates configuration that a human is looking at. The dry-run preview and the backups are the parts that make it defensible.

The token efficiency claim is also architectural rather than marketing. The README says responses are lean JSON to minimize token usage. Every entity state you return to a model costs context, and a Home Assistant instance with hundreds of entities will blow through a context window fast if the server returns verbose payloads.

Installing Hass-MCP with Docker and Connecting Claude

The README recommends Docker. Pull the image first:

docker pull voska/hass-mcp:latest

Then register the server in Claude Desktop's claude_desktop_config.json. The README gives this exact shape, with the token passed through from the environment:

{
  "mcpServers": {
    "hass-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HA_URL", "-e", "HA_TOKEN", "voska/hass-mcp"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}

Replace the token placeholder and adjust HA_URL. If Home Assistant runs on the same machine under Docker Desktop on Mac or Windows, the README says to use http://host.docker.internal:8123. If Home Assistant itself runs in Docker on the same host, the README notes you may need to add --network host, or use the machine's IP address instead. After saving, restart Claude Desktop and the Hass-MCP tool should appear in the tools menu.

The uv route avoids Docker entirely. Install uv, then point the client at the published package:

{
  "mcpServers": {
    "hass-mcp": {
      "command": "uvx",
      "args": ["hass-mcp"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
      }
    }
  }
}

For the Claude Code CLI, the README shows a single registration command:

claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp

A first real use is a state query rather than a control action: ask the model which entities exist in a domain, or ask for the state of a specific sensor, and check that the entity IDs it reports match your own Home Assistant interface. Only after that should you let it toggle anything.

HTTP Mode Is Powerful and Undefended by Default

The streamable HTTP transport is where the design trade-off is sharpest. It is genuinely useful: stateless mode with JSON responses and no Mcp-Session-Id makes horizontal scaling straightforward, and it is the only way to serve LibreChat, OpenWebUI or a shared gateway from one process.

The README's own caution block is blunt. HTTP mode exposes full Home Assistant control over the network. Anyone who can reach the port can call any tool: turn off lights, unlock doors, trigger automations, restart Home Assistant. The README states that the MCP specification does not yet ship a built-in auth layer in this server, and that until it does you must put it behind a reverse proxy doing basic-auth or bearer-token validation, a VPN or zero-trust network such as Tailscale, WireGuard or Cloudflare Access, or localhost binding only.

That is not a footnote. It means the HTTP mode is a deployment you have to finish yourself. The default binding is 127.0.0.1, and the README says to change --host only if you know what you are doing. If you are not going to run an authenticating proxy, use stdio with a local client and leave the port closed.

Where Hass-MCP Is the Wrong Tool

Do not reach for this as an automation engine. Home Assistant's own automations, scripts and scenes run on triggers and conditions inside the instance. Hass-MCP lists and controls automations, and the README mentions prompts for creating them, but it does not replace the runtime that executes them. If your goal is a motion sensor turning on a light at night, this project is not in that path.

Do not use it as a general-purpose Home Assistant client either. It is scoped to MCP clients. There is no web UI, no mobile app, and the README does not document a standalone interactive mode.

The sharper failure mode is latency and context. Every tool call is a round trip through an LLM, and the server's responses consume context. A question that spans many domains will produce a lot of tool calls. The README's lean JSON helps, but it does not make a chat interface a substitute for a dashboard you glance at.

Finally, the token is a real credential. A long-lived access token grants whatever that user can do. Anything that reaches the server reaches Home Assistant with that token's authority, which is exactly why the HTTP caution block exists.

Hass-MCP Compared with a Direct Home Assistant Integration

The obvious alternative is not another MCP server but the Home Assistant integration path: point a client at Home Assistant's own REST API with a long-lived token, or use an existing conversational agent integration built for Home Assistant. The difference in approach is who owns the tool schema. With a direct REST call, the model or the caller must know the endpoint shape, the entity ID and the service name. With Hass-MCP, the server owns that vocabulary and exposes it as MCP tools, so search, domain summaries and entity listing become first-class operations rather than things you construct by hand.

The second alternative is an MCP server that only reads state. Hass-MCP deliberately includes control and dashboard editing. That is a wider blast radius and a wider capability set at the same time. If you want the model to answer questions about your home but never change anything, the read-only subset of these tools is what you would restrict to, and the README does not describe a read-only mode, so that restriction has to come from the token or the network layer.

Maintenance, Licensing and Upgrade Cost

The repository is not archived, and the last push was on 2026-08-06, which is recent. Releases have moved steadily: v0.4.1 on 2026-05-17, v0.5.0 on 2026-06-23, and v0.6.0 on 2026-08-06. That cadence suggests the project is being worked on, though the README does not document a deprecation policy or a compatibility guarantee between versions.

Versioning is derived from git tags through hatch-vcs, and the Dockerfile notes that the build stage needs .git for that derivation. A practical consequence: building the image from a source tree without git metadata will not produce the expected version. The wheel is built in a first stage and installed into a runtime stage, so the published image does not carry the build toolchain.

The runtime constraint worth checking before you commit is Python 3.13 or newer, declared in pyproject.toml and matched by the Dockerfile's python3.13 base. If your environment is pinned to an older interpreter, the uvx path will not work for you.

The licence is MIT, which is permissive and places few obligations on how you redistribute or modify the code. That is a statement about the licence text, not legal advice about your specific use.

Upgrade cost is low by design. Configuration lives in two environment variables, so a version bump is a tag change or an image pull. The riskier upgrades are the ones touching dashboard editing, since that path writes to Lovelace configuration. The README mentions automatic backups and a dry-run preview, but it does not document how to restore from those backups or where they are stored.

Editorial conclusion

Adopt Hass-MCP if you already run Home Assistant, want Claude or another MCP client to query and control entities, and are comfortable putting an HTTP deployment behind a reverse proxy or VPN. Skip it if you need a full automation engine or an unauthenticated public endpoint, because the README states the server ships no built-in auth layer for HTTP. Verify first that your Home Assistant long-lived token has only the scope you intend to hand to the model, and that the container can actually reach HA_URL from where it runs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. voska/hass-mcp on GitHub