ha-mcp: an MCP server that lets Claude, ChatGPT and Gemini drive Home Assistant

The problem ha-mcp solves for Home Assistant owners

Home Assistant already exposes a REST API, a WebSocket API and a service-call surface. What it does not expose is a vocabulary an LLM can use without being told the entity IDs, the service names and the argument shapes every time. ha-mcp fills that gap: it is a Model Context Protocol server that presents Home Assistant as a set of callable tools, so an AI assistant can query states, execute services and manage automations from natural language. The README describes it as "A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Home Assistant."

The audience is specific. You already run Home Assistant, you already use an MCP-capable client such as Claude Desktop, Claude.ai, ChatGPT or Gemini, and you want the assistant to reach into your instance rather than you copying entity IDs into a chat window. The README badge says 87 tools; the alt text on the same badge says 95+, which is a small inconsistency worth noting before you trust either number.

This is not a Home Assistant integration in the usual sense, and it is not an official Nabu Casa product. The repository name says "unofficial" and the README repeats it. That matters because the tool surface touches your entire instance.

How the in-process server, webhook URL and tool layer fit together

The architecture has three parts. First, a server process that speaks MCP and holds a connection to Home Assistant. Second, a transport: either stdio for local clients, or Streamable HTTP for network clients. Third, a tool layer that maps MCP tool calls onto Home Assistant's own APIs, with a WebSocket connection enabled by default because the .env.example notes it is "essential for async operations".

The recommended deployment collapses the first two. The HA-MCP Custom Component installs through HACS and runs the full server inside the Home Assistant process itself. There is no separate container and no long-lived access token to manage, because the server already lives inside the instance it controls. The README states this works on Home Assistant OS, Supervised, Container and Core with full feature parity.

Clients connect through a URL. The Configure screen produces a webhook URL of the form `https://<your-ha-domain>/api/webhook/<webhook-id>`, routed through Nabu Casa or any reverse proxy already pointed at Home Assistant. Locally the same screen gives `http://<ha-host>:8123/api/webhook/<webhook-id>`. For same-network clients the server is also reachable directly at `http://<ha-ip>:9584/private_<random>`. That second URL is a shared secret in the path, not an authenticated endpoint, unless you change the setting.

The Docker path keeps the classic shape: a container with `HOMEASSISTANT_URL` and `HOMEASSISTANT_TOKEN` environment variables, serving Streamable HTTP on port 8086. The compose file sets `command: ha-mcp-web` because, as its comment explains, a detached service has no stdin for the image's default stdio mode.

Installing ha-mcp through HACS and connecting your first client

The README calls the custom component "the easiest setup in every case". The steps below are the ones it lists.

Add the integration repository to HACS. In HACS, open Integrations, then the overflow menu, then Custom repositories, and add the URL with category Integration.

https://github.com/homeassistant-ai/ha-mcp-integration

Download it, then restart Home Assistant. After the restart, go to Settings, Devices & Services, Add Integration, search for HA-MCP Custom Component, choose HA-MCP Server and submit. Creating the entry starts the server. A notification confirms the start and points you at the Configure screen, and the connect URL is also printed in the Home Assistant log.

Copy that URL and paste it into your MCP client. If your client runs on the same machine or network, the direct port form is shorter:

http://<ha-ip>:9584/private_<random>

If you would rather not expose anything, turn off Remote access via webhook in the entry options. The README says no webhook is registered at all in that case, while the direct port and the sidebar panel keep working. To require a Home Assistant sign-in instead of treating the URL as the credential, set Webhook authentication to `ha_auth`.

The Docker route is for people who already run compose. Add the service to your existing file, set the token in the environment, and bring it up:

services:
  ha-mcp:
    image: homeassistant-ai/ha-mcp:latest
    command: ha-mcp-web
    ports:
      - "8086:8086"
    volumes:
      - ha-mcp-data:/home/mcpuser/.ha-mcp
    environment:
      - HOMEASSISTANT_URL=http://homeassistant:8123
      - HOMEASSISTANT_TOKEN=${HA_TOKEN}

The named volume is not optional in practice. The compose comments state that without it, every settings change is lost when the container is re-created, and several settings ask you to restart before they take effect.

Running two install methods at once is the failure mode to avoid

The README is unusually direct about this: configure exactly one install method per client. The in-process server is a complete standalone install that "takes the place of the app (add-on), Docker, and uvx/PyPI (stdio) methods." It also says not to run the in-process server alongside another install.

The reason is not stated in the README, but the shape of the problem is visible. Two servers pointed at the same Home Assistant instance both hold WebSocket connections, both register tools under the same names, and both may register a webhook. A client that discovers two servers sees duplicate tools, and which one answers is not deterministic. If you migrate from the add-on to the custom component, remove the add-on rather than leaving it stopped, because a stopped add-on can be restarted by an update or by habit.

The second constraint is Python version, and it only bites the standalone route. The pyproject file sets `requires-python = ">=3.13,<3.15"`. A comment explains the upper bound was widened so the package installs on Home Assistant's interpreter when run in-process, since HA core-2026.7 ships Python 3.14. If you are on an older Python for the uvx or PyPI path, the install fails before anything else runs.

The third is a breaking change rather than a limitation. The README's first line states that as of v7.3.0, `ha_config_set_yaml` moved to beta. Any automation or prompt that assumed that tool is generally available needs to be checked against `docs/beta.md`.

ha-mcp against the official MCP route and plain REST scripting

The obvious alternative is Home Assistant's own conversational agent and Assist pipeline. The difference in approach is where the language model sits. Assist runs inside Home Assistant, matches intents against exposed entities, and never leaves the instance. ha-mcp does the opposite: the model runs in your client, and Home Assistant is exposed as tools over MCP. That gives you a much wider model choice and much richer tool arguments, at the cost of sending entity names, states and service calls out to whichever provider you configured.

A second alternative is writing scripts against the REST API yourself. That is more work per automation but has no third-party server in the path, no MCP transport, and no dependency on a project whose releases are currently dev builds. If your goal is a single scheduled action, a REST call or a native automation is the smaller system.

The distinction people search for as ha mcp versus official mcp is really this: ha-mcp is a community server that wraps the Home Assistant API, not a Nabu Casa product. Nothing in the README claims official status, and the project name says unofficial.

Maintenance, licence and what upgrading actually costs

The repository is not archived, and the last push was on 2026-09-09. The three most recent releases are all dev builds from the same day: v8.4.3.dev2608, v8.4.3.dev2605 and v8.4.3.dev2602. The pyproject version is 8.4.3. If you pin to a release tag, be aware that the newest tags are development builds, not stable ones.

The licence is MIT, and the Dockerfile labels the image `org.opencontainers.image.licenses="MIT"`. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice travel with it. That is a statement about the licence text, not legal advice for your situation.

Upgrade cost concentrates in three places. The custom component upgrades through HACS, which means a Home Assistant restart. The Docker image updates when you pull a new tag, and the compose comments warn that a re-created container loses settings without the `ha-mcp-data` volume. The standalone package pins `fastmcp==3.4.7` exactly while leaving httpx, pydantic and others as ranges, so a FastMCP bump is a hard pin change rather than a range move. The pyproject comments also note that `websockets` is deliberately absent from the dependency list because ha-mcp ships a private vendored copy under `src/ha_mcp/_vendor/websockets`, synced by `scripts/vendor_websockets.py`. Vendoring removes version conflicts with Home Assistant's own constraints, and it also means websockets security updates arrive only when that sync script runs.

Where ha-mcp is the wrong tool

If you want a voice assistant that answers in the kitchen without a cloud round trip, ha-mcp is not that. It assumes an MCP client, which in practice means a desktop or web chat application, not a satellite speaker.

If your Home Assistant instance is reachable from the internet and you plan to use the webhook URL as the credential, understand what you are doing. The setting exists to replace that with a Home Assistant sign-in, and the README documents it, which suggests the maintainers consider the secret-URL mode a convenience rather than a security boundary.

If you need documented rollback, the README does not provide it. There is a backups mention in the sidebar panel description and a `BACKUP_HINT` environment variable in the compose file, but no procedure for reverting a tool change. Treat any write-capable tool as something you test on an instance you can restore from a snapshot you took yourself.

Finally, if your instance has many automations, the search tools have time budgets. The .env.example documents `HAMCP_AUTOMATION_CONFIG_TIME_BUDGET=30`, `HAMCP_SCRIPT_CONFIG_TIME_BUDGET=20` and `HAMCP_SCENE_CONFIG_TIME_BUDGET=20`, and says to raise them on instances with many automations. Leaving them at defaults means `ha_search` can return a partial result rather than a complete one, and the README does not describe how a client is told the result was truncated.

Editorial conclusion

Adopt ha-mcp if you run Home Assistant OS, Supervised, Container or Core and want an AI client to read states, call services and manage automations through MCP. Skip it if you cannot accept an LLM holding a long-lived token or an admin-level webhook URL, or if you need documented rollback semantics, which the README does not provide. Verify first that only one install method is running per client, that the HA-MCP sidebar panel appears after the restart, and that your Python is 3.13 or 3.14 if you use the PyPI route.

Frequently asked questions

Official sources

1. homeassistant-ai/ha-mcp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases