# ha-mcp

> An MCP server that lets AI assistants build, configure and debug a Home Assistant smart home

- Category: Agents & Automation / Workflow Automation
- Language: Python
- Licence: MIT
- Repository: https://github.com/homeassistant-ai/ha-mcp
- Website: https://homeassistant-ai.github.io/ha-mcp/
- Canonical page: https://ai-tldr.dev/tools/ha-mcp/
- Updated: 2026-11-11

## In short

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.

1. 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.

2. 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.

3. 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.

4. 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.

```bash
uvx --python 3.14 ha-mcp@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

## Version history

- 2026-11-11 v9.2.0: ha-mcp 9.2.0 moves to Python 3.14, answers helper flows through Home Assistant Core's own flow, adds exact-match search/replace for stored text files, and redacts flow fields that Core marks as secret.