ha-mcp is a Model Context Protocol (MCP) server that lets AI assistants read and change a Home Assistant instance. Beyond controlling devices and querying states, it creates and edits automations, scripts, scenes, helpers, and dashboards, debugs automations from execution traces, reads history and logs, and manages backups, apps, HACS, and the device and entity registries. It is built with FastMCP.
It runs in several ways: as a custom component that hosts the full server in-process on every Home Assistant deployment type, with a webhook URL for remote clients and a direct local port; as a Home Assistant app (add-on); as a Docker or PyPI streamable-HTTP server; or over stdio. Remote access can go through Nabu Casa or a reverse proxy, a webhook-proxy app, an OpenAI tunnel for ChatGPT connectors behind a firewall, or an OIDC identity provider. A setup wizard generates client configuration for Claude Code, Gemini CLI, ChatGPT, Open WebUI, VS Code, Cursor, and other clients, and a hosted demo environment is available for trying it before connecting a real instance.
The catalogue holds 88 tools. An optional search-based discovery mode replaces the full list with a BM25 search tool plus separate read, write, and delete call tools, so an MCP client can apply distinct approval policies per category and smaller or local models are not handed every tool schema at once. Safety controls include a read-only mode, per-tool enable and disable, tool security policies that require user approval, and automatic backups before edits. Opt-in beta tools backed by the custom component add file access and YAML editing of configuration.yaml.
Home Assistant's own MCP Server integration is built on the Assist pipeline; the two differ as follows:
| Capability | Built-in MCP Server | ha-mcp |
|---|---|---|
| Control exposed devices, query states | Yes | Yes |
| Entity scope | Only entities exposed to Assist | Everything in Home Assistant |
| Create / edit automations, scripts, scenes | No | Yes |
| Build & edit dashboards | No | Yes |
| Debug automations from traces, read history & logs | No | Yes |
| Manage helpers, areas, zones, labels, groups | No | Yes |
| Backups, apps, HACS, device & entity registry | No | Yes |
Home Assistant Agent Skills are bundled and served as MCP resources via skill:// URIs, and reachable through the hagetskill_guide tool for clients without resource support. They encode conventions such as native constructs over Jinja2 workarounds, helper selection, refactoring workflows, and automation modes.
Features
- Search and discovery: fuzzy entity search, deep configuration search, and a system overview
- Device control: any service call, bulk device control, and real-time states
- Configuration management: automations, scripts, scenes, helpers, dashboards, areas, floors, zones, groups, labels, calendars, and blueprints
- Monitoring: history, statistics, camera snapshots, automation traces, logs, and ZHA device data
- System operations: backup and restore, updates, apps, HACS, integrations, and the device and entity registries
- Safety controls: read-only mode, per-tool enable/disable, approval-gated security policies, and automatic edit backups
- Tool discovery mode: hasearchtools, hacallreadtool, hacallwritetool, and hacalldeletetool behind ENABLETOOL_SEARCH
- Deployment options: in-process custom component, Home Assistant app, Docker, PyPI/uvx, or stdio
- Remote access: webhook URLs through Nabu Casa or a reverse proxy, a webhook-proxy app, an OpenAI tunnel, and OIDC authentication
- Bundled skills: Home Assistant best-practice guides served as MCP resources or through hagetskill_guide
- Beta file tools: list, read, write, and delete files in allowed directories and edit top-level YAML keys with validation and backups
