Ha MCP

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

HA-MCP — Manage Home Assistant with AI

Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants.

---

---

🚀 Get Started

The recommended way to run ha-mcp is the HA-MCP integration. It installs into Home Assistant through HACS (the built-in Marketplace on Home Assistant 2026.11+), 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: setup asks for an administrator access token and how clients may connect.

Add it to Home Assistant via HACS or, on Home Assistant 2026.11+, the Marketplace (the preferred install):

Quick start:

The setup below is for version 9.0.0 (October 28, 2026) and later; earlier versions show a shorter setup form without the administrator account step.

1. Install the HA-MCP integration (requires Home Assistant 2026.8.0 or newer; see compatibility details). On Home Assistant 2026.8–2026.10, open HACS, search for HA-MCP, then Download. On Home Assistant 2026.11 or newer, open Settings → Marketplace, accept its first-run warning, and search for HA-MCP, then Install. HA-MCP is in the default catalog, so installing it and receiving its updates do not require connecting GitHub or adding a custom repository. The badge above also opens its catalog page. Already installed from the earlier homeassistant-ai/ha-mcp-integration repository? It keeps receiving the same releases. On the Marketplace, keep GitHub connected for its background checks on that custom repository. Older installed releases may still appear as HA-MCP Custom Component; searching for HA-MCP matches both names.
2. Restart Home Assistant.
3. Decide which administrator account the server acts as. Either create a long-lived access token on your own account (your profile → Security → Long-lived access tokens → Create token; it works from anywhere if it leaks, and the server's changes show under your name), or, safer, create an account just for HA-MCP under Settings → People → Add person with Allow login, Local access only and Administrator on. Never use your own login for the second option.
4. Go to Settings → Devices & Services → Add Integration, search for HA-MCP and choose HA-MCP Server. Paste your token, or enter the user name and password of the account you made for HA-MCP (HA-MCP creates its token), pick how clients may connect — Remote access through Home Assistant (start with Secret URL, the simplest; Home Assistant sign-in adds a login) and/or Network access: Local network — then click Submit. Both start disabled, so a client on another device needs one of them.
5. Copy the connect URL from the entry's Configure screen (Settings → Devices & Services → “HA-MCP — Manage Home Assistant with AI” → HA-MCP Server → Configure). A notification confirms the server started and points you there.
6. 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? Leave remote access disabled at setup (or 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 Authentication mode to ha_auth to require a Home Assistant account sign-in instead of using the secret URL as the credential.
• Manual install (no HACS or Marketplace): 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 →

🏠 Home Assistant app (add-on)

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.

Other install methods

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.

🌐 Remote access (Nabu Casa / Webhook Proxy app / OpenAI Tunnel)

Using the HA-MCP custom component? You do not need the Webhook Proxy — the component has its own built-in webhook for remote access (see the Get Started quick start at the top). The proxy is for the app (it can also front another external server via its mcp_server_url option). The OpenAI Tunnel below is different: it applies to any install method when Home Assistant isn't publicly reachable at all (no Nabu Casa or reverse proxy).

Already have Nabu Casa or another reverse proxy pointing at your Home Assistant? The Webhook Proxy app routes MCP traffic through your existing setup — no separate tunnel or port forwarding needed.

1. Install the MCP Server app (see above) and the Webhook Proxy app from the same store
2. Start the webhook proxy and restart Home Assistant when prompted
3. Copy the webhook URL from the app logs:

   MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx
   

4. Configure your AI client with that URL

For other remote access methods (Cloudflare Tunnel, custom reverse proxy), see the Setup Wizard.

ChatGPT / Codex behind a firewall (OpenAI Tunnel). ChatGPT connectors normally require a publicly reachable URL. If you can't (or don't want to) expose one, the community OpenAI Tunnel for HA-MCP integration by @norpol runs OpenAI's tunnel-client inside Home Assistant and connects your local MCP server URL to an OpenAI-hosted tunnel over an outbound-only connection — no port forwarding, reverse proxy, or public URL. Point it at your ha-mcp URL, then attach the ChatGPT connector to the same tunnel ID. See the FAQ entry and #1811.

Webhook proxy documentation →

🧪 Demo server (Windows / macOS / Linux)

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.

🍎 macOS

1. Go to claude.ai and sign in (or create a free account)
2. Open Terminal and run:

   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh
   

3. Download Claude Desktop (or restart: Claude menu → Quit)
4. Ask Claude: "Can you see my Home Assistant?"

You're now connected to the demo environment! Connect your own Home Assistant →

🐧 Linux

Anthropic doesn't ship Claude Desktop for Linux, so pick one path:

Claude Desktop — free, via the community build:

1. Install the community Claude Desktop for Linux build and sign in with a free claude.ai account
2. Open Terminal and run:

   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
   

3. Restart Claude Desktop, then ask: "Can you see my Home Assistant?"

Claude Code — official CLI, requires a paid Claude plan:

1. Install Claude Code: curl -fsSL https://claude.ai/install.sh | bash
2. Configure ha-mcp, then run claude:

   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code
   

3. Start claude, run /mcp to confirm, then ask: "Can you see my Home Assistant?"

Full Linux guide →

🪟 Windows

1. Go to claude.ai and sign in (or create a free account)
2. Open Windows PowerShell (from Start menu) and run:

   irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex
   

3. Download Claude Desktop (or restart: File → Exit)
4. Ask Claude: "Can you see my Home Assistant?"

You're now connected to the demo environment! Connect your own Home Assistant →

🧙 Setup Wizard for 15+ clients

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

Having issues? Check the FAQ & Troubleshooting

---

💬 What Can You Do With It?

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

You Say	What Happens
"Create an automation that turns on the porch light at sunset"	Creates the automation with proper triggers and actions
"Add a weather card to my dashboard"	Updates your Lovelace dashboard with the new card
"The motion sensor automation isn't working, debug it"	Analyzes execution traces, identifies the issue, suggests fixes
"Make my morning routine automation also turn on the coffee maker"	Reads the existing automation, adds the new action, updates it
"Create a script that sets movie mode: dim lights, close blinds, turn on TV"	Creates a reusable script with the sequence of actions

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

---

✨ Features

Category	Capabilities
🔍 Search	Fuzzy entity search, deep config search, system overview
🏠 Control	Any service, bulk device control, real-time states
🔧 Manage	Automations, scripts, helpers, dashboards, areas, zones, groups, calendars, blueprints
📊 Monitor	History, statistics, camera snapshots, automation traces, ZHA devices
💾 System	Backup/restore, updates, apps, device registry
🔒 Safety	Read Only Mode toggle, per-tool enable/disable, tool security policies (user approval), automatic edit backups

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.

Complete Tool List (87 tools)

Category	Tools
Apps (add-ons)	ha_get_app, ha_manage_app
Areas & Floors	ha_list_floors_areas, ha_remove_area_or_floor, ha_set_area_or_floor
Assist	ha_manage_pipeline
Automations	ha_config_get_automation, ha_config_remove_automation, ha_config_set_automation
Blueprints	ha_manage_blueprints
Calendar	ha_config_get_calendar_events, ha_config_remove_calendar_event, ha_config_set_calendar_event
Camera	ha_get_camera_image
Dashboard	ha_get_dashboard_screenshot (beta)
Dashboards	ha_config_delete_dashboard_resource, ha_config_delete_dashboard, ha_config_get_dashboard, ha_config_list_dashboard_resources, ha_config_set_dashboard_resource, ha_config_set_dashboard
Developer	ha_dev_manage_server, ha_dev_manage_settings
Device Registry	ha_get_device, ha_remove_device, ha_set_device
Energy	ha_manage_energy_prefs
Entity Registry	ha_get_entity_exposure, ha_get_entity, ha_remove_entity, ha_set_entity
Files	ha_delete_file (beta), ha_list_files (beta), ha_read_file (beta), ha_write_file (beta)
Groups	ha_config_list_groups, ha_config_remove_group, ha_config_set_group
HACS	ha_get_hacs_info, ha_manage_hacs
Helper Entities	ha_config_list_helpers, ha_config_set_helper, ha_remove_helpers_integrations
History & Statistics	ha_get_automation_traces, ha_get_history, ha_get_logs
Integrations	ha_get_integration, ha_get_system_health, ha_set_integration
Labels & Categories	ha_config_get_category, ha_config_get_label, ha_config_remove_category, ha_config_remove_label, ha_config_set_category, ha_config_set_label
Matter	ha_manage_radio
Scenes	ha_config_get_scene, ha_config_remove_scene, ha_config_set_scene
Scripts	ha_config_get_script, ha_config_remove_script, ha_config_set_script
Search & Discovery	ha_get_overview, ha_get_state, ha_search
Service & Device Control	ha_bulk_control, ha_call_event, ha_call_service, ha_get_operation_status, ha_list_services
System	ha_config_get_yaml (beta), ha_config_set_yaml (beta), ha_manage_backup, ha_manage_custom_tool (beta), ha_manage_security_policy, ha_manage_theme, ha_manage_updates, ha_reload_core, ha_restart
Todo Lists	ha_get_todo, ha_remove_todo_item, ha_set_todo_item
Utilities	ha_eval_template, ha_report_issue
Zones	ha_get_zone, ha_remove_zone, ha_set_zone

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.

---

🆚 ha-mcp vs. Home Assistant's built-in MCP Server

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:

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

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.

---

🔌 Custom Component (ha_mcp_tools) — File & YAML Services

The HA-MCP integration 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:

Tool	Description
ha_config_set_yaml (beta)	Safely add, replace, or remove top-level YAML keys in configuration.yaml and package files (automatic backup, validation, and config check)
ha_list_files (beta)	List files in allowed directories
ha_read_file (beta)	Read files from allowed paths (config YAML, logs, and allowed directories)
ha_write_file (beta)	Write files to allowed directories
ha_delete_file (beta)	Delete files from allowed directories

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

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

Requires Home Assistant 2026.8.0 or newer through HACS or the Marketplace; see compatibility details for manual installs. On Home Assistant 2026.8–2026.10: open HACS, search for HA-MCP, and Download. On 2026.11 or newer: open Marketplace, accept the first-run warning, search for HA-MCP, and Install. The main repository is in the default catalog for both. 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, 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 →.

---

🧠 Better Results with Agent Skills

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.

Bundled Skills (built-in)

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.

---

🔍 Tool Discovery for AI Agents

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.

Smaller or local LLMs (Ollama, etc.)

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.

Enable search-based discovery

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:

Tool	Purpose
ha_search_tools	BM25 English-keyword search across all tools, pinned ones included. A hidden tool comes back compact: name, one-line description (the docstring's first paragraph), a one-line params list (types, enum values, required) and the proxy that executes it. ha_search_tools(tools=[...]) returns the full definition (description, input schema and annotations) of the named tools, the second hop before a call. A pinned tool returns a name-only stub (pinned: true) pointing back at the tool list, and does not use up a result slot.
ha_call_read_tool	Execute a readOnlyHint tool by name. Safe — clients can auto-approve.
ha_call_write_tool	Execute a write tool that creates or updates data.
ha_call_delete_tool	Execute a tool that removes / deletes data.

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.

Setting	Default	Description
ENABLE_TOOL_SEARCH	false	Replace full tool catalog with search-based discovery (tools deferred behind on-demand search).
TOOL_SEARCH_MAX_RESULTS	5	Max hidden tools returned per ha_search_tools call (range 2–10); a pinned tool that ranks inside that top count is added as a name-only stub on top of it.
PINNED_TOOLS	empty	Comma-separated tool names to keep always visible. The web settings UI is the primary way to manage this.

When to enable

• Claude Haiku, OpenAI-compatible local models, Gemini, or any model without native deferred tool support

…