ha-mcp: A Home Assistant MCP Server That Runs Inside Home Assistant Itself

What ha-mcp Solves and Who It Is For

ha-mcp is a Model Context Protocol server that gives AI assistants a structured interface to Home Assistant. Instead of asking an assistant to guess at REST API calls or parse YAML, you give it tools that control devices, query states, execute services, and manage automations. The README counts 87 tools, though the badge says 95+, so the exact number depends on feature flags and version. The project targets anyone running Home Assistant who wants natural-language control from Claude Desktop, Claude.ai, ChatGPT, or any other MCP client. The intended user is not a casual tinkerer. You need to be comfortable adding a custom repository to HACS, reading logs for a connect URL, and deciding between several install methods. The project is unofficial, which means it is not maintained by the Home Assistant core team, and the MIT license confirms you can use it freely but without warranty.

The In-Process Custom Component Is the Architectural Centerpiece

Most MCP servers for home automation run as a separate process that talks to Home Assistant over its API. ha-mcp offers that too, but its recommended path is different. The HA-MCP Custom Component installs into Home Assistant through HACS and runs the full MCP server in-process, inside the Home Assistant Python environment. The README says this works on every installation type: Home Assistant OS, Supervised, Container, and Core. Because the server shares the process with Home Assistant, there is no access token to manage. Authentication is handled by the webhook URL itself, which acts as a secret, or optionally by requiring a Home Assistant account sign-in. This design removes a whole class of configuration errors around long-lived access tokens. The trade-off is that you must not run the in-process server alongside another ha-mcp install method. The docs are explicit: run only one. If you already run the Docker image or a stdio process, adding the component would create two servers competing for the same client connections.

Getting It Running: HACS, Add-On, or Plain Python

The README gives three concrete install paths. The preferred one is the HACS custom component. You add the repository https://github.com/homeassistant-ai/ha-mcp-integration as a custom integration, download it, restart Home Assistant, then add the HA-MCP Server entry from Settings, Devices & Services. After submission, the server starts and prints a connect URL in the log. That URL is either a webhook through your Nabu Casa domain or reverse proxy, like https://<your-ha-domain>/api/webhook/<webhook-id>, or a direct local address at http://<ha-ip>:9584/private_<random>. You paste the URL into your AI client. The second path is the Home Assistant app, formerly the add-on, available on Home Assistant OS and Supervised. You add the repository https://github.com/homeassistant-ai/ha-mcp to the Apps store, install Home Assistant MCP Server, start it, and read the Logs tab for the MCP URL. No token setup is needed there either. The third path, implied but not detailed in the excerpt, is the app, Docker, or uvx/PyPI stdio method that the component replaces. The README positions the component as the easiest in every case, and the absence of a token step supports that claim for local and remote clients alike.

Feature Scope and the Optional File and YAML Tools

The tool set covers the core Home Assistant operations: controlling devices, querying entity states, executing services, and managing automations. The README's badge claims 87 tools, and the banner text says 95+, so the inventory is version-dependent. A notable split is the File & YAML services entry. It is a second entry type in the custom component, and you only need it if you enable ha-mcp's opt-in file and YAML editing tools. Those tools are off by default and controlled by feature flags. The v7.3.0 breaking change moved ha_config_set_yaml to beta, which signals that YAML editing is not considered stable. If your workflow depends on editing configuration.yaml through an assistant, you are relying on a beta path that may change. The settings panel in the sidebar lets an admin manage tools, feature flags, backups, and themes. That panel is a useful operational surface, but it is admin-only, so a non-admin user cannot reconfigure the server without elevated rights.

Genuine Limitations and Failure Modes

The most concrete limitation is the single-install rule. The README warns not to run the in-process server alongside another ha-mcp install method. If you forget and start both, you will have two servers exposing the same Home Assistant instance to MCP clients, which can produce duplicate tool definitions or conflicting state. A second limitation is the remote access model. The webhook URL is the credential. If that URL leaks, anyone with it can call the server until you disable or rotate the webhook. The optional ha_auth authentication mitigates that by requiring a Home Assistant account sign-in, but it is not the default. A third limitation is the beta status of YAML editing. The project moved ha_config_set_yaml to beta in v7.3.0, which means the tool's behavior may change without notice. For production automation that edits configuration files, that is a risk. Finally, the project's release cadence is aggressive. The recent releases show three dev builds in a single day, v8.4.3.dev2608, dev2605, and dev2602. Frequent dev builds mean you should pin to a stable release rather than tracking master if you want predictable behavior.

Alternatives and the Difference in Approach

The main alternative is running an MCP server as a separate process, either through the project's own Docker or uvx/PyPI stdio method, or through a different project entirely. The Home Assistant project itself does not ship an official MCP server, so the field is dominated by community efforts. A generic alternative is to skip MCP and use Home Assistant's built-in conversation agent with a local LLM, which avoids installing anything but gives you less structured tool access. The difference in approach matters: ha-mcp's in-process component treats the MCP server as part of Home Assistant, sharing its lifecycle and authentication. A separate-process server, by contrast, runs independently and must authenticate through the Home Assistant REST API, typically with a long-lived access token. That separation makes the server easier to debug in isolation but adds token management and a network hop. If you need to connect an MCP client that is not on your local network, the component's webhook approach through Nabu Casa is simpler than configuring port forwarding for a standalone server.

Maintenance, Licensing, and Upgrade Cost

The project is actively maintained. The default branch is master, the repository is not archived, and the last push was September 2026. The release list shows multiple dev builds per day, which indicates a high commit velocity but also means you should expect frequent updates. The license is MIT, which permits commercial use, modification, and redistribution with attribution. There is no copyleft obligation, so you can embed the server in a proprietary product if you keep the license notice. The upgrade cost is moderate. Because the project uses feature flags and beta moves, an upgrade can change which tools are available or move a tool from stable to beta, as happened with ha_config_set_yaml in v7.3.0. You should read the breaking-change notes before each major upgrade. The README also notes that the in-process component replaces the app, Docker, and stdio methods, so if you upgrade from an older install method to the component, you must remove the old one. The project's own documentation is the source of truth for migration steps, and the setup wizard at the documentation site can generate client-specific config, which reduces the cost of switching clients.

Editorial conclusion

Adopt ha-mcp if you run Home Assistant and want a single, actively maintained MCP server that covers device control, state queries, service calls, and automation management. The in-process custom component is the clearest choice for OS, Supervised, Container, and Core installs because it avoids token handling and works remotely through your existing webhook. Skip it if you need YAML editing (a beta feature), if your AI client only speaks stdio and you dislike managing a separate process, or if you cannot tolerate the churn of frequent dev builds. Before adopting, verify the current breaking-change log for v7.3.0 and later, confirm your Home Assistant version meets the Python requirement, and decide whether the webhook URL or the direct port fits your network topology. The project's own docs warn to run exactly one install method per client, so pick the component or the add-on and do not mix them.

Official sources

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