Open-Source ha-mcp Gives AI Agents 87 Tools to Run Your Smart Home
An unofficial MCP server exposes 87 Home Assistant tools to Claude, ChatGPT, and other LLMs for building, debugging, and controlling smart homes.
Takeaways
- ha-mcp is an unofficial Home Assistant MCP server exposing 87 tools for AI assistants.
- Unlike HA's built-in MCP, it covers full config: automations, dashboards, traces, registries, backups, HACS.
- Recommended install is an in-process custom component via HACS, working on all HA install types.
- Also ships as Docker image, PyPI package (
uvx ha-mcp@latest), and local stdio for demos. - Optional BM25 tool search mode for small-context models like Haiku, Gemini, or local Ollama runtimes.
- Safety features include Read Only Mode, per-tool approval policies, automatic edit backups, and
/readonlyURL suffix.
Home Assistant's built-in MCP integration lets AI clients read and control devices exposed to Assist. The open-source ha-mcp project broadens that connection to automation authoring, dashboard editing, trace analysis, registry management, and selected system operations. Its GitHub repository has 5.4k stars. The broader API lets an agent carry a task from diagnosis through an approved configuration change.
Inside the 87-tool surface
Model Context Protocol, or MCP, lets an AI client discover and invoke tools described by machine-readable schemas. ha-mcp sits between the client and a Home Assistant instance, exposing 87 tools across search, control, management, monitoring, system, and safety categories. The catalog covers:
- Building: automations, scripts, scenes, blueprints, helpers, and dashboards.
- Organizing: areas, zones, labels, calendars, and the device and entity registries.
- Diagnosing: logs, execution traces, history, camera snapshots, and backups.
- Administering: HACS, Z-Wave radios, Matter fabrics, and selected configuration files.
Home Assistant's built-in server routes requests through the Assist pipeline, which limits clients to exposed entities and supported intents. ha-mcp adds administrative workflows governed by its enabled tools, credentials, connection mode, and security policies.
| Capability | Built-in MCP | ha-mcp |
|---|---|---|
| Entity scope | Entities exposed to Assist | Entities and APIs covered by enabled tools |
| Typical work | Read state, run intents, control devices | Create, inspect, debug, and manage configuration |
| Permission boundary | Assist exposure settings | Read-only mode, tool policies, approvals, and feature flags |
Four routes to a running server
The maintainers recommend the HA-MCP Custom Component for access to the complete tool set. It installs through HACS, runs inside Home Assistant, and supports Home Assistant OS, Supervised, Container, and Core installations.
| Path | Runtime | Use case |
|---|---|---|
| Custom component | In-process through HACS | Complete feature set, including component-only file and YAML tools |
| Docker | ghcr.io/homeassistant-ai/ha-mcp |
Separate container or service deployment |
| PyPI | uvx ha-mcp@latest |
Streamable HTTP server without a Home Assistant component |
| stdio | Local process | Local MCP clients and development |
The custom component's setup collects an administrator access token and connection settings, then returns a webhook URL for the MCP client. Both values grant sensitive access and should be stored as credentials. The project uses the MIT license and has no usage fee, though connected model providers and clients may charge for inference or subscriptions.
Prompts that produce configuration
Clients can translate plain-English requests into one or more Home Assistant tool calls. The README demonstrates tasks such as:
Create an automation that turns on the porch light at sunset.
Add a weather card to my dashboard.
The motion sensor automation isn't working. Debug it.
Create a script that sets movie mode: dim lights, close blinds, turn on the TV.
A failed automation shows the value of the wider tool surface. The agent can retrieve execution traces, inspect history and logs, identify the condition or action that failed, and tie a proposed fix to the recorded run. Any resulting edit remains subject to the client's approval flow and the server's write policies.
Keeping tool schemas under control
An MCP client normally receives a schema for every advertised tool. Loading 87 schemas consumes context in clients that lack deferred tool loading, leaving fewer tokens for the request, Home Assistant state, and model response. ha-mcp addresses that cost with BM25 search, a term-ranking method that returns tools relevant to a query.
With ENABLE_TOOL_SEARCH=true, the server advertises four discovery and proxy tools alongside a small pinned set such as ha_search, ha_get_overview, and ha_report_issue:
ha_search_toolsfinds tools matching the requested task.ha_call_read_toolinvokes operations that retrieve data.ha_call_write_toolinvokes operations that change state or configuration.ha_call_delete_toolinvokes destructive operations.
Discovered tools remain callable by exact name. Separating proxy calls by mutation level also gives MCP clients clear permission classes, allowing automatic approval for reads, prompts for writes, and explicit confirmation for deletes.
- Smaller and local models: Claude Haiku, Gemini, and OpenAI-compatible local models can reduce idle schema use.
- Clients with tool caps: A compact catalog of roughly 10 visible tools stays below limits such as 100 tools.
- Clients with deferred loading: claude.ai, Claude Desktop, and Claude Code can retain the full catalog because unused schemas carry no idle context cost.
Connection-specific URL suffixes override the global catalog setting. Appending /catalog/search, /catalog/full, or /readonly applies that behavior to one client, allowing several clients to share a server with different tool surfaces.
Boundaries for write access
Administrator-level credentials make configuration errors and unintended device actions consequential. ha-mcp provides several controls for narrowing that access:
- A global Read Only Mode hides write tools.
- Per-tool settings enable or disable individual operations.
- User-approval policies require confirmation for sensitive calls.
- Automatic edit backups preserve prior configuration.
- Beta feature flags gate privileged tools such as
ha_write_fileandha_config_set_yaml. - File and YAML operations require the custom component.
Appending /readonly creates a connection-scoped observer endpoint. That connection hides write tools and rejects write calls made through cached tool definitions or search proxies. It can inspect states, logs, and traces without mutating the installation.
Access tokens and webhook URLs should remain outside source control, logs, and shared prompts. Independent Home Assistant backups cover failure modes beyond individual configuration edits, including device actions and broader system changes.
Skills teach Home Assistant conventions
The companion skills repository packages domain guidance for structuring automations, helpers, dashboards, and templates. These guides help models choose native Home Assistant constructs, select appropriate helper types, and produce configurations that remain understandable after the agent finishes.
Skills ship as MCP resources under skill:// URIs, allowing resource-aware clients to discover them automatically. Tool-only clients can retrieve the best-practices guide through ha_get_skill_guide. A model can therefore pair operations such as ha_config_set_automation with guidance on when templates, native triggers, or helpers fit the task.
Pick the smallest surface that works
Home Assistant's built-in MCP server suits clients that need state queries, Assist intents, and control of explicitly exposed entities. ha-mcp suits development and maintenance workflows that require configuration authoring, registry access, trace analysis, or system administration. Its trace-to-edit workflow can shorten automation debugging by keeping evidence, diagnosis, and remediation in one client session.
The file and YAML write tools retain a beta label, so read-only endpoints and approval policies provide a controlled path for evaluation. For MCP server developers, the project also demonstrates two reusable patterns: search-based discovery contains schema costs, while mutation-specific proxies expose permission boundaries that clients can enforce directly.