What is ha-mcp?
ha-mcp is a Model Context Protocol server that connects an AI assistant to a Home Assistant installation so the assistant can do more than flip switches. With 87 tools, it can search entities and configuration, call any service, and create or edit automations, scripts, helpers, dashboards, areas, zones, groups, calendars and blueprints. It sits in the Workflow Automation category of the Agents & Automation tools and is open-source, written in Python and licensed MIT.
Overview
ha-mcp is a Model Context Protocol server that connects an AI assistant to a Home Assistant installation so the assistant can do more than flip switches. With 87 tools, it can search entities and configuration, call any service, and create or edit automations, scripts, helpers, dashboards, areas, zones, groups, calendars and blueprints. It can also read history, statistics, camera snapshots and automation traces, which is what lets an assistant debug a rule that does not fire. It is a community project in the homeassistant-ai GitHub organisation, started by @julienld, written in Python on FastMCP and released under the MIT license.
The README draws a clear line between ha-mcp and Home Assistant's built-in MCP Server. The built-in server sits on the Assist pipeline and only sees the entities exposed to Assist, which suits voice-style control. ha-mcp is meant for building and maintaining the setup itself: it covers all entities and adds editing, trace and log debugging, backups, apps, HACS and the registries. The project's rule of thumb is to use the built-in server to control devices and ha-mcp when the assistant should also change how the house is configured.
Safety controls are part of the design: a Read Only Mode toggle, per-tool enable and disable, tool policies that ask the user for approval, and automatic backups before edits. The server runs locally, and the project states there is no telemetry. For small or local models that struggle with a long tool list, an optional search-based discovery mode replaces the 87 tools with four entry points plus pinned tools. A setup wizard covers 15+ clients, including Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Open WebUI, VS Code and Cursor.
What it does
- 87 MCP tools across search, control, configuration, monitoring and system management
- Creates and edits automations, scripts, helpers, dashboards, areas, zones, groups, calendars and blueprints
- Debugging from history, statistics, camera snapshots, automation traces and logs
- Backup and restore, updates, apps and device-registry management
- Safety: Read Only Mode, per-tool enable/disable, approval policies and automatic edit backups
- Bundled Home Assistant agent skills served as MCP resources at skill:// URIs
- Optional search-based tool discovery (ENABLE_TOOL_SEARCH) for smaller or local models
- Runs locally with no telemetry; works with 15+ AI clients through a setup wizard
Getting started
The recommended install is the HA-MCP integration, which runs the server inside Home Assistant (2026.8.0 or newer). Docker, PyPI/uvx and a Home Assistant app (add-on) are also supported; run only one install method per client.
Install the integration
On Home Assistant 2026.11 or newer, open Settings → Marketplace, search for HA-MCP and click Install. On 2026.8–2026.10, open HACS, search for HA-MCP and click Download. Then restart Home Assistant.
Choose the account the server acts as
Create a long-lived access token on your profile, or (the safer option) a dedicated administrator person with local access only under Settings → People.
Add the HA-MCP Server integration
Go to Settings → Devices & Services → Add Integration, choose HA-MCP Server, enter the token or account, and pick a remote access method (Secret URL is the simplest) and/or local network access. Copy the connect URL from the entry's Configure screen and paste it into your AI client.
Or run it from PyPI
Outside Home Assistant, the server can run with uvx. The setup wizard on the project site gives the exact client configuration.
uvx --python 3.14 ha-mcp@latestCommands and code are distilled from the project's own documentation — always check the official repo for the latest.
When to use it
- Reach for it to ask an assistant for a new automation in plain language, such as turning on the porch light at sunset
- Reach for it when an automation is not working and you want the assistant to read its trace and fix it
- Reach for it to build or change a dashboard without editing YAML by hand
- Reach for its Read Only Mode when you want an assistant to inspect a home without being able to change it
How ha-mcp compares
ha-mcp alongside other open-source workflow automation tools AI/TLDR tracks, ranked by GitHub stars.
| Tool | Stars | What it does |
|---|---|---|
| n8n | ★ 210k | A self-hostable workflow automation tool with a visual node editor that connects 400+ apps and APIs and adds native AI steps, letting technical teams build automations without writing most of the glue code. |
| Huginn | ★ 50.5k | A self-hosted system of "agents" that watch websites, feeds, and events and take automated actions on your behalf, similar to a private IFTTT. |
| GitHub MCP Server | ★ 34.4k | GitHub's official MCP server, hosted or self-run, that gives an agent scoped toolsets for repositories, issues, pull requests, Actions runs and code-security alerts. |
| gws (Google Workspace CLI) | ★ 32.3k | A command-line tool for every Google Workspace API, built at runtime from Google’s Discovery Service, returning structured JSON and shipping 40+ agent skills. Not an officially supported Google product. |
| Kestra | ★ 30.2k | An event-driven orchestration platform that defines data, AI, and infrastructure pipelines as declarative YAML and runs them through a web UI. |
| Activepieces | ★ 25.5k | An open-source Zapier alternative where you build automations from reusable TypeScript "pieces", with support for AI agents and self-hosting. |
| n8n-MCP | ★ 23.2k | An MCP server that gives coding assistants structured access to n8n's node catalogue, schemas, docs and workflow templates so they can build and validate n8n workflows. |
| ha-mcp | ★ 7.6k | An MCP server that lets AI assistants build, configure and debug a Home Assistant smart home |