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

The Unofficial and Awesome Home Assistant MCP Server

🚀 Get Started

Set up for your operating system — you'll pick Local (Claude Desktop) or the Home Assistant App on the setup page:

Prefer to set it up by hand? The detailed paths are below.

🏠 Recommended: Home Assistant App (add-on)

Running Home Assistant OS? Run ha-mcp inside Home Assistant — no access token to manage, works with Claude Desktop, Claude.ai, ChatGPT and any other MCP client, and can stay on your local network or be configured for remote / HTTP 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: App Store → ⋮ → Repositories, then paste https://github.com/homeassistant-ai/ha-mcp.

2. Install "Home Assistant MCP Server" from the App Store 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 add-on documentation →

⚠️ Two ways to run ha-mcp — don't mix them. The add-on above is the recommended path. The local stdio path below runs ha-mcp on your own computer; it is more advanced, has fewer features, and is behind most connection problems. If you use the add-on, your Claude Desktop config points at the add-on URL through mcp-proxy with no token — do not also keep a local uvx ha-mcp@latest entry (with HOMEASSISTANT_URL / HOMEASSISTANT_TOKEN) in your Claude Desktop config. Running both at once is a known cause of connection hangs.

Not on Home Assistant OS? Home Assistant Container and Core installs can't run add-ons, but the HA-MCP Custom Component (ha_mcp_tools) can run the full ha-mcp server in-process, inside Home Assistant — no separate Docker container, no token to manage. It works on Home Assistant OS too, and coexists with the add-on. The connect URL is a Home Assistant webhook, so it reaches remote MCP clients through Nabu Casa (or any reverse proxy) with no extra tunnel.

1. Install HA-MCP Custom Component from HACS (the same repository you use for ha-mcp), or copy custom_components/ha_mcp_tools from this repository into your Home Assistant config/custom_components/ directory; then restart Home Assistant
2. Add the integration (Settings → Devices & Services → Add Integration → HA-MCP Custom Component) and choose HA-MCP Server from the menu, then submit — creating the entry starts the server
3. Copy the connect URL from the HA-MCP Server notification (also shown on the entry's Configure screen)
4. Manage the server from the HA-MCP sidebar panel (admin-only web settings UI)
5. Connect your AI client to that URL

Full in-process server documentation →

💻 Run locally with Claude Desktop (stdio · advanced)

No paid subscription required. This runs ha-mcp on your own machine over stdio.

Quick install (~5 min)

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

   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 →

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:
   sh

   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:
   sh

   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 →

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

   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 →

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

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

   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.

Webhook proxy documentation →

🧙 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:

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

✨ Features

🆚 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:

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) (beta)

Some tools require a companion custom component installed in Home Assistant. Standard HA APIs do not expose file system access or YAML config editing. This component provides both.

Tools that require the component:

All other tools work without the component. These five return an error with installation instructions if the component is missing.

These tools also require feature flags: HAMCP_ENABLE_FILESYSTEM_TOOLS=true (file tools) and ENABLE_YAML_CONFIG_EDITING=true (YAML editing). To enable the ha_install_mcp_tools installer tool, set HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true.

Install using HACS (recommended)

To add manually: open HACS > Integrations > three-dot menu > Custom repositories > add https://github.com/homeassistant-ai/ha-mcp (category: Integration) > Download.

After installing, restart Home Assistant. Then open Settings > Devices & Services > Add Integration and search for HA-MCP Custom Component.

Want a server too? Add the HA-MCP Server entry (see the in-process server section below) — it runs the full server inside Home Assistant on every install type. The add-on remains available from the add-on store for Home Assistant OS / Supervised users who prefer it.

Install manually

Copy custom_components/ha_mcp_tools/ from this repository into your HA config/custom_components/ directory. Restart Home Assistant, then add the integration as described above.

Run the MCP server inside Home Assistant (in-process server entry)

The HA-MCP Custom Component offers a second config-entry type, HA-MCP Server, that runs the full ha-mcp server in-process, inside Home Assistant, and exposes it remotely through a Home Assistant webhook. This is a full install method in its own right — useful for Home Assistant Container / Core users who can't run add-ons, and available on Home Assistant OS too (it coexists with the add-on on a different default port, 9584 vs 9583).

• Install: install HA-MCP Custom Component from HACS, or copy custom_components/ha_mcp_tools into your config/custom_components/ directory and restart Home Assistant. Then Add Integration → HA-MCP Custom Component → HA-MCP Server and submit — creating the entry starts the server.
• Connect URL: appears in the HA-MCP Server notification and on the entry's Configure screen. It's a Home Assistant webhook — https://<nabu-casa-domain>/api/webhook/<id> remotely (through Nabu Casa or any reverse proxy) or http://<home-assistant-host>:8123/api/webhook/<id> locally. The server is also reachable directly on its own port by default (set Network access to 127.0.0.1 to turn direct access off).
• Settings panel: while the server runs, an admin-only HA-MCP panel in the Home Assistant sidebar opens its web settings UI (enable/disable/pin tools, feature flags, backups, themes) through Home Assistant itself — no loopback URL needed, the same idea as the add-on's "Open Web UI" button.
• Authentication: by default the secret webhook URL is the credential; optionally require Home Assistant account sign-in (ha_auth) for clients that support it.
• Release channel: the entry options let you pick stable (the pinned release) or dev (the latest development build, refreshed on every reload/restart).
• The HA MCP Tools services entry is optional but recommended alongside it — that second entry type of the same component provides the privileged file/YAML services the server's file tools use, exactly as with the add-on, Docker, and pip installs.

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 same skills are reachable through the polymorphic ha_get_skill_guide tool — call it with no args to list bundled skills, with a skill arg to list its files, or with skill + file to read content. 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 (~84 tools) is listed to the client through the standard MCP tools/list response. Clients with deferred / on-demand tool loading (Claude Sonnet, Claude Opus) handle that fine — tools are pulled into context only when needed, so idle context cost is near-zero.

For models without deferred tool support — Claude Haiku, Gemini, ChatGPT OpenAI-compatible local models, smaller open-weights models — 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 add-on 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 add-on). The full catalog is replaced in the tool list with four entry points plus a small set of always-visible "pinned" tools (ha_search_entities, ha_get_overview, ha_restart, 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.

When to enable

• Claude Haiku, OpenAI-compatible local models, Gemini, ChatGPT or any model without native deferred tool support — large idle-context savings.
• MCP clients that cap total tool count (some cap at 100) — surfaces a minimal set (~10 tools) instead of 84.
• Cost-sensitive deployments — fewer idle tokens per turn.

Leave it off when using Claude Sonnet/Opus or any client with deferred tool loading; the full catalog has no idle cost there and direct calls skip the search step. If you choose to use our toolsearch then you should disable the native Claude Opus/Sonnet toolsearch, which is called deferred tools in the settings.

🔄 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 add-on 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, tools shown as available will return Unknown tool when called.

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

🧪 Dev Channel

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 add-on.

🤝 Contributing

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

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

🔒 Privacy

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.

📄 License

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

🙏 Acknowledgments

• 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).

👥 Contributors

Maintainers

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

Contributors

• @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 HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION in the add-on 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 addon API calls to route through HA Core ingress proxy instead of direct container connections, fixing ha_manage_addon proxy mode on addon 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_addon 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! ☕

💬 Community

• GitHub Discussions — Ask questions, share ideas
• Issue Tracker — Report bugs, request features, or suggest tool behavior improvements

⭐ Star History