homeassistant-ai/ha-mcp

Breaking change (v7.3.0): ha_config_set_yaml has been moved to beta.

The Unofficial and Awesome Home Assistant MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Home Assistant.
Using natural language, control smart home devices, query states, execute services and manage your automations.

The recommended way to run ha-mcp is the HA-MCP Custom Component. It installs into Home Assistant through HACS, runs the full server in-process, and works on every Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case, with no access token to manage.

Add it to Home Assistant via HACS (the preferred install):

Quick start:

1. Install the HA-MCP Custom Component from HACS — click the badge above, or in HACS open Integrations → ⋮ → Custom repositories, add https://github.com/homeassistant-ai/ha-mcp-integration (category: Integration), then Download.
2. Restart Home Assistant.
3. Go to Settings → Devices & Services → Add Integration, search for HA-MCP Custom Component, choose HA-MCP Server, and click Submit. Creating the entry starts the server.
4. Copy the connect URL from the entry's Configure screen (Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure) — it is also printed in the Home Assistant log. A notification confirms the server started and points you there.
5. Paste that URL into your AI client — done.

Connect URL. The Configure screen gives you a Home Assistant webhook URL for remote clients — https://<your-ha-domain>/api/webhook/<webhook-id> through Nabu Casa or any reverse proxy already pointed at Home Assistant (locally, http://<ha-host>:8123/api/webhook/<webhook-id>). For clients on the same network, the server is also reachable directly at http://<ha-ip>:9584/private_<random>.

• Replaces other install methods: the in-process server is a complete, standalone ha-mcp install — it takes the place of the app (add-on), Docker, and uvx/PyPI (stdio) methods. Run only one; do not run the in-process server alongside another install.
• Local only? Turn off Remote access via webhook in the entry options — no webhook is registered at all, while the direct port and sidebar panel keep working.
• Settings panel: while the server runs, an admin-only HA-MCP panel appears in the Home Assistant sidebar for managing tools, feature flags, backups, and themes.
• Optional authentication: set Webhook authentication to ha_auth to require a Home Assistant account sign-in instead of using the secret URL as the credential.
• Manual install (no HACS): copy custom_components/ha_mcp_tools/ from this repository into your Home Assistant config/custom_components/ directory, then restart and add the integration as above.

The component's second entry type, the File & YAML services entry (HA-MCP File & YAML Tools), is only needed if you enable ha-mcp's opt-in file and YAML editing tools (feature flags, off by default) — skip it otherwise; you can add it later at any time. It works with any server type (in-process, app, Docker, or stdio).

Full in-process server documentation → · Setup Wizard for client-specific config →

Prefer to run ha-mcp as a Home Assistant app (add-on)? On Home Assistant OS and Supervised installs it is a close second — no access token to manage, and it works with Claude Desktop, Claude.ai, ChatGPT, and any other MCP client on your local network or configured for remote access.

1. Add the repository to your Home Assistant instance:

   

   If that opens the App store without an add-repository dialog (a known Home Assistant issue), add it manually: Settings → Apps → Install app → ⋮ → Repositories, then paste https://github.com/homeassistant-ai/ha-mcp.

2. Install "Home Assistant MCP Server" from Settings → Apps → Install app and click Start. (Home Assistant 2026.2 renamed "Add-ons" to "Apps"; on older versions this is the Add-on store.)

3. Open the Logs tab to find your unique MCP URL.

4. Connect your AI client to that URL — no token or credential setup needed.

Full app documentation →

⚠️ Configure exactly one install method per client. The custom component, the app, Docker/PyPI, and local stdio are independent ways to run the same server — pick one and point your AI client at that single URL. Keeping two entries for the same server in one client (for example a local uvx ha-mcp@latest entry with HOMEASSISTANT_URL / HOMEASSISTANT_TOKEN alongside an app or component URL) is a known cause of connection hangs.

These run the server outside Home Assistant — useful for Container / Core installs (which can't run apps) or a separate host. The Setup Wizard generates the exact client-specific config for each.

• Docker (HTTP server): run ghcr.io/homeassistant-ai/ha-mcp in HTTP mode, pointed at your Home Assistant URL and a long-lived token (an administrator's is recommended; non-admin tokens work with limitations), and connect your client to its secret URL. See the Setup Wizard for the full command and per-client config.

• PyPI / uvx (HTTP server): run the published ha-mcp package with uvx ha-mcp@latest (or pip) as a streamable-HTTP server the same way. Details in the Setup Wizard.

• Local stdio (not recommended): runs ha-mcp on your own machine over stdio. The one-command installers in the Demo server section below use this path; the Setup Wizard covers connecting it to your own Home Assistant.

• OIDC authentication: gate remote access behind an external identity provider (Authentik, Keycloak, Auth0, etc.) instead of a secret URL — all authenticated users share the server's Home Assistant credentials. See OIDC Mode.

  ⚠️ stdio has known transport issues. The stdio transport has connection problems that streamable HTTP does not (#1713). It is recommended only for demo/testing tinkering — for a real setup, use the custom component or an HTTP method above.

Want to try ha-mcp before connecting your own Home Assistant? No paid subscription required. These one-command scripts set up a local stdio connection to a hosted demo environment so you can see it working in a few minutes. Each script's Connect your own Home Assistant link then shows how to point it at your instance.

Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor, and more.

Having issues? Check the FAQ & Troubleshooting

Just talk to Claude naturally. Here are some real examples:

Spend less time configuring, more time enjoying your smart home.

Template helper edit backups capture persisted options through the HA-MCP custom component, using either its Server entry or File & YAML Tools entry. Helper edits, generic integration options edits, and deletion capture the stable config-entry identity and entity ID/name mapping. Capture refuses degraded secret scrubbing. Restoring an existing helper requires a fresh safety backup, removes optional settings absent from the snapshot, and verifies persisted options.

For Template backup listing and bulk deletion, filter by the config-entry ID returned as entity_id by capture. Capture accepts an entity alias; the history filters use the stable config-entry ID. Recreation reports its replacement config-entry ID and saved entity mapping separately.

If the original entry has been deleted, restore recreates the helper and reports its new config-entry ID. The saved entity ID and custom name are restored when available; an occupied entity ID is refused before creation. Older snapshots without entity metadata cannot preserve renamed entity IDs. If a collision or verification failure occurs after creation, the new helper and source backup are retained and the result reports the new entry for inspection. Other entity/device registry settings are not restored. Helper and integration edits through the same server wait until restore finishes; other Home Assistant clients are outside this coordination. Failed or uncertain restores report their outcome and safe refusal reasons; inspect the current helper before retrying.

Z-Wave configuration values can be read through ha_manage_radio with action="get_config_params" or action="get_config_param", even when their configuration entities are disabled or absent. Reads use the Z-Wave JS cache by default; a single full root parameter can explicitly request a device read. See parameter reads, freshness, and examples.

Home Assistant ships its own MCP Server integration. It is built on the Assist pipeline, so a connected MCP client can read and control the entities you have exposed to Assist and run the intents Assist understands — handy for voice-style control of already-exposed devices.

ha-mcp is a standalone server built for configuring, building, and debugging your smart home, not just controlling it. On top of device control, it adds capabilities the built-in integration does not have:

Rule of thumb: Use the built-in integration for voice-style control of devices you have already exposed; use ha-mcp when you want an AI assistant that can also build and maintain your Home Assistant setup.

The HA-MCP Custom Component also powers a set of privileged tools that standard Home Assistant APIs can't provide: file system access and YAML config editing. (The same component runs the full server in-process — that's the recommended install in the Get Started section at the top.) Its File & YAML services entry (HA-MCP File & YAML Tools) enables the tools below.

Tools that require the component:

Template helper edit backups and restores also require the component, using either its Server entry or File & YAML Tools entry. These five tools return an error with installation instructions if the component is missing.

These tools also require beta feature flags. See Beta Features for how to enable them — including the ENABLE_BETA_FEATURES master flag, which must be on before the filesystem/YAML sub-flags take effect.

Install the HA-MCP File & YAML Tools entry from the same HA-MCP Custom Component:

To add manually: open HACS > Integrations > three-dot menu > Custom repositories > add https://github.com/homeassistant-ai/ha-mcp-integration (category: Integration) > Download. Or copy custom_components/ha_mcp_tools/ from this repository into your HA config/custom_components/ directory.

After installing, restart Home Assistant, then open Settings > Devices & Services > Add Integration, search for HA-MCP Custom Component, and add the HA-MCP File & YAML Tools entry.

To run the full ha-mcp server in-process through this same component, see the Get Started section at the top and the full in-process server documentation →.

This server gives your AI agent tools to control Home Assistant. For better configurations, pair it with Home Assistant Agent Skills — domain knowledge that teaches the agent Home Assistant best practices.

An MCP server can create automations, helpers, and dashboards, but it has no opinion on how to structure them. Without domain knowledge, agents tend to over-rely on templates, pick the wrong helper type, or produce automations that are hard to maintain. The skills fill that gap: native constructs over Jinja2 workarounds, correct helper selection, safe refactoring workflows, and proper use of automation modes.

Skills from homeassistant-ai/skills are bundled and served as MCP resources via skill:// URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed. For tool-only clients (claude.ai, etc.), the best-practices skill is reachable through the ha_get_skill_guide tool: call it with no arguments to read SKILL.md, or with file set to a path SKILL.md links to read that reference file. Resources are not auto-injected into context — clients must explicitly request them, so idle context cost is just the metadata listing.

ha_get_skill_guide is a mandatory tool: the catalog always exposes it (it can't be disabled) so tool-only clients never see a silently missing skill surface.

Skills can still be installed manually for clients that prefer local skill files — see the skills repo for instructions.

By default, the full tool catalog (~87 tools) is listed to the client through the standard MCP tools/list response. Clients with deferred / on-demand tool loading (claude.ai, Claude Desktop, Claude Code) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.

For setups without deferred tool support — models like Claude Haiku, Gemini, OpenAI-compatible local models and smaller open-weights models, or clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI) — listing the full tool catalog up front adds a lot of idle context and can overwhelm smaller models. To address that, the server ships with a search-based discovery mode built on top of FastMCP's BM25 search transform.

If your model can't see the tools or your Home Assistant, it may be getting handed the whole tool catalog at once and struggling with it. It's recommended to try the following to see if it helps:

• Enable tool search (ENABLE_TOOL_SEARCH=true, or the app option below). Instead of listing every tool up front, the server defers the catalog behind a search interface so the model pulls in only the tools it needs, when it needs them.
• Raise the model's context window above the default. Local runtimes ship with small defaults (Ollama's num_ctx is one example) that can't hold a large tool set plus the conversation — increase it well beyond the default.

Set ENABLE_TOOL_SEARCH=true (or toggle the option in the HA app). The full catalog is replaced in the tool list with four entry points plus a small set of always-visible "pinned" tools (ha_search, ha_get_overview, ha_report_issue, etc.). All tools remain callable directly by name once discovered:

The proxy split lets MCP clients apply different permission policies per category (e.g. auto-approve reads, prompt for writes, confirm deletes) without parsing tool docstrings.

A ha_manage_* tool combines several operations, so it is reachable from more than one proxy: ha_call_write_tool and ha_call_delete_tool run the whole tool, while ha_call_read_tool runs only the read actions Read Only Mode approves (the same per-call verdict), so a manage tool with no approved read actions is not reachable there. Search results list each proxy the tool can be reached through. In Read Only Mode only ha_call_read_tool is listed; the other two still answer a client that holds them in a cached tool list, and any write they carry gets the Read Only Mode error rather than Unknown tool.

• Claude Haiku, OpenAI-compatible local models, Gemini, or any model without native deferred tool support — large idle-context savings. The same applies to clients that inline all tool schemas regardless of model (e.g. GitHub Copilot CLI, even when running Claude Sonnet/Opus).
• MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 87.
• Cost-sensitive deployments — fewer idle tokens per turn.

Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.

🔄 Refresh your client's tool list after changing this (or any) setting. Toggling ENABLE_TOOL_SEARCH (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its cached tool list until it re-fetches. Restarting the app or Home Assistant does not refresh the client — reconnect or refresh the MCP server in your client (e.g. re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop). If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (Unknown tool, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after re-adding, delete the connector and create a new one with a different name.

For the HA app, the same option is documented in homeassistant-addon/DOCS.md along with the in-app settings UI for fine-grained tool enable/disable/pin.

Append /readonly to the server's HTTP MCP endpoint to restrict that connection to the existing Read Only Mode while other clients keep normal access:

Normal:     https://example.com/private_your_secret
Read-only:  https://example.com/private_your_secret/readonly

OAuth and OIDC connections use the same login/provider: for example, https://example.com/mcp/readonly. No additional secret or server is required. Read-only connections hide write tools and block write calls, including calls through cached tools or search proxies. The global Read Only Mode setting still restricts both endpoints when enabled. Reconnect the client after changing its URL so it refreshes its tool list.

This is a connection mode for automated agents, not a separate permission on the credential: the same credentials still work at the normal endpoint. Home Assistant webhook URLs also accept the suffix: https://your-ha.example/api/webhook/<webhook-id>/readonly. This requires the updated embedded integration or Webhook Proxy dev app (add-on), together with the updated MCP server.

Want early access to new features and fixes? Dev releases (.devN) are published on every push to master.

Dev Channel Documentation — Instructions for pip/uvx, Docker, and Home Assistant app.

For development setup, testing instructions, and contribution guidelines, see CONTRIBUTING.md.

For comprehensive testing documentation, see tests/README.md.

Ha-mcp runs locally on your machine. Your smart home data stays on your network.

• No telemetry today — anonymous usage stats are a planned future feature (as of June 2026); when it lands it will follow your Home Assistant analytics/telemetry setting (which you can override), announced prominently in the release notes and the web Settings UI at least one month beforehand
• No personal data collection — we never collect entity names, configs, or device data
• User-controlled bug reports — only sent with your explicit approval

For full details, see our Privacy Policy.

This project is licensed under the MIT License - see the LICENSE file for details.

• Home Assistant: Amazing smart home platform (!)
• FastMCP: Excellent MCP server framework
• Model Context Protocol: Standardized AI-application communication
• Claude Code: AI-powered coding assistant
• PolicyLayer: Argument-path predicate DSL shape (args.domain in [...] with eq/in/regex/contains/exists/...) inspired the per-tool approval rule schema (#966).

• @julienld — Project creator.
• @sergeykad — Core maintainer.
• @kingpanther13 — Core maintainer.
• @Patch76 — Core maintainer.

• @bigeric08 — Explicit mcp dependency for protocol version 2025-11-25 support.
• @airlabno — Support for data field in schedule time blocks.
• @ryphez — Codex Desktop UI MCP quick setup guide.
• @Danm72 — Entity registry tools (ha_set_entity, ha_get_entity) for managing entity properties.
• @Raygooo — SOCKS proxy support.
• @cj-elevate — Integration & entity management tools (enable/disable/delete); person/zone/tag config store routing.
• @maxperron — Beta testing.
• @kingbear2 — Windows UV setup guide.
• @konradwalsh — Financial support via GitHub Sponsors. Thank you! ☕
• @knowald — Area resolution via device registry in ha_get_system_overview for entities assigned through their parent device. Financial support via GitHub Sponsors. Thank you! ☕
• @zorrobyte — Per-client WebSocket credentials in OAuth mode, fixing WebSocket tool failures.
• @deanbenson — Fixed ha_deep_search timeout on large Home Assistant instances with many automations.
• @saphid — Config entry options flow tools (initial design, #590).
• @adraguidev — Fix menu-based config entry flows for group helpers (#647).
• @transportrefer — Integration options inspection (ha_get_integration schema support, #689).
• @teh-hippo — Fix blueprint import missing save step.
• @smenzer — Documentation fix.
• @The-Greg-O — REST API for config entry deletion.
• @restriction — Responsible disclosure: python_transform sandbox missing call target validation.
• @lcrostarosa — Diagnostic and health monitoring tools concept (#675), inspiring system/error logs, repairs, and ZHA radio metrics integration.
• @roysha1 — Copilot CLI support in the installation wizard; replaced placeholder logo SVGs with real brand icons on the documentation site.
• @teancom — Fix add-on stats endpoint (/addons/{slug}/stats).
• @TomasDJo — Category support for automations, scripts, and scenes.
• @bzelch — python_transform support for automations and scripts.
• @gcormier — Windows installer improvements: removed unused variable and fixed terminal closing after install.
• @ekobres — Feature flags for HAMCP_ENABLE_FILESYSTEM_TOOLS and the (since removed) HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION in the app config, with beta tagging in source and docs.
• @w3z315 — Financial support via GitHub Sponsors. Thank you! ☕
• @griffinmartin — Added OpenCode (by Anomaly) as a selectable AI client in the setup wizard, with both stdio and streamable HTTP support.
• @hhopke — Fixed app (add-on) API calls to route through HA Core ingress proxy instead of direct container connections, fixing ha_manage_addon (now ha_manage_app) proxy mode on app installs.
• @tomwilkie — JMESPath middleware exploration (#1147) whose review-time token-measurement data informed the design of #1199 and #1225.
• @SealKan — fields=/attribute_keys= projection on six read-heavy tools (#1225), ha_call_event tool (#1239), dashboards-list helper refactor (#1207), for:-field duration-math detector in the best-practice checker (#1264), persistent DCR OAuth client registrations across restarts (#1265), and issue-triage prompt token-budgeting (#1522).
• @KarelTestSpecial — Cached YAML instance to prevent CPU spikes during bulk edits (#1371).
• @corgan2222 — HA brand assets for custom integration (#1317).
• @drseanwing — Progress emission via FastMCP Context in long-running tools (#1124); tool-discovery / categorized-search docs (#1123).
• @fnordpig — Config subentry support (#1393) and Assist pipeline management tool (#1392).
• @paul43210 — array_patch mode in ha_manage_app for atomic GET-modify-POST (#1063).
• @L1AD — Filed #966 proposing tool security policies; pointed to PolicyLayer's MCP-security work as prior art that inspired the predicate DSL shape.
• @nightcityblade — Updated stale Home Assistant Advanced Mode references after HA 2026.6 made formerly advanced options available by default (#1533).
• @emmelutzer — Financial support via GitHub Sponsors. Thank you! ☕
• @pkkr — ha_knx_get_project tool exposing KNX group addresses from an uploaded ETS project file.
• @cbowns — Fixed inconsistent hyphen in setup.astro Codex CLI docs.
• @Shaan-alpha — Extended ha_restart known-good error patterns to cover 502/503 responses from reverse proxies.
• @rebelancap — Fixed UTC-to-local timezone conversion in add_timezone_metadata.
• @saevras — Fixed blueprint import E2E test to use local URL instead of host-to-container networking.
• @jasonjhofmann — Recurring calendar events via rrule support in ha_config_set_calendar_event.
• @vpciii — Coerce JSON-encoded strings on dict/list tool params.
• @pburtchaell — Financial support via GitHub Sponsors. Thank you! ☕
• @norpol — Built the OpenAI Tunnel for HA-MCP companion integration, connecting ChatGPT to a firewalled Home Assistant MCP server (#1811).

• GitHub Discussions — Ask questions, share ideas
• Issue Tracker — Report bugs, request features, or suggest tool behavior improvements. Bug reports need the report the ha_report_issue tool generates, or a reason why there is none; without either they are closed after 24 hours.