Ha MCP is a community Model Context Protocol (MCP) server for Home Assistant. An MCP client such as Claude Desktop, Claude Code, ChatGPT, Open WebUI, VS Code, or Cursor connects to it and can then control devices, query states, call services, and create or edit automations, scripts, scenes, helpers, and dashboards from natural-language requests. It is positioned for configuring, building, and debugging a smart home, not only controlling it.
Home Assistant ships its own MCP Server integration built on the Assist pipeline, which covers entities exposed to Assist and the intents Assist understands. Ha MCP is a standalone server that reaches everything in Home Assistant and adds what the built-in integration lacks:
| 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 and edit dashboards | No | Yes |
| Debug automations from traces, read history and logs | No | Yes |
| Manage helpers, areas, zones, labels, groups | No | Yes |
| Backups, apps, HACS, device and entity registry | No | Yes |
The recommended deployment is a custom component installed through HACS that runs the full server in-process on every Home Assistant installation type, reachable on the local network or remotely through a Home Assistant webhook via Nabu Casa or a reverse proxy. An add-on, a Docker image, and a stdio install are alternatives, and a hosted demo environment lets you try it before connecting your own instance. The custom component also powers privileged opt-in tools for file access and YAML config editing that the standard Home Assistant APIs do not offer. The server runs locally and your smart home data stays on your network.
The catalog holds about 87 tools. Clients with deferred tool loading receive the full list, and an optional search-based discovery mode (built on FastMCP's BM25 search transform) hides the catalog behind a search tool plus three typed proxies for read, write, and delete calls, so smaller models, Gemini, OpenAI-compatible local models, or clients that inline every schema stay within context limits and clients can apply a different approval policy per category. Home Assistant Agent Skills are bundled and served as MCP resources to teach the agent Home Assistant conventions such as native constructs over template workarounds and correct helper selection.
Features
- Search: fuzzy entity search, deep config search, and a system overview
- Control: call any service, bulk device control, and real-time states
- Manage: automations, scripts, helpers, dashboards, areas, zones, groups, calendars, and blueprints
- Monitor: history, statistics, camera snapshots, automation traces, ZHA devices, and Z-Wave configuration parameters
- System: backup and restore, updates, apps, HACS, and the device and entity registries
- Safety: a Read Only Mode toggle, per-tool enable or disable, tool security policies with user approval, and automatic backups before edits
- Read-only connections: a read-only HTTP endpoint suffix restricts one connection to Read Only Mode while other clients keep normal access
- Tool discovery mode: optional BM25 search over the tool catalog with separate read, write, and delete proxies for smaller models and schema-inlining clients
- Bundled skills: Home Assistant Agent Skills served as MCP resources, plus a guide tool for clients without resource support
- File and YAML tools: opt-in beta tools, powered by the custom component, that list, read, and write allowed files and edit top-level YAML keys with backup and config check
- Deployment options: in-process custom component via HACS, a Home Assistant add-on, Docker, or stdio, with a setup wizard for over 15 MCP clients
- Settings panel: an admin-only Home Assistant sidebar panel for tools, feature flags, backups, and themes
