# The Unofficial and Home Assistant MCP Server

> Source: <https://github.com/homeassistant-ai/ha-mcp>
> Published: 2026-06-16 10:29:42+00:00

Breaking change (v7.3.0):`ha_config_set_yaml`

has been moved to[beta].

*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.*

*No paid subscription required.* Click on your operating system:

**🍎 macOS**

- Go to
[claude.ai](https://claude.ai)and sign in (or create a free account) - Open
**Terminal** and run:

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

[Download Claude Desktop](https://claude.ai/download)(or restart: Claude menu → Quit)- Ask Claude:
**"Can you see my Home Assistant?"**

You're now connected to the demo environment! [Connect your own Home Assistant →](https://homeassistant-ai.github.io/ha-mcp/guide-macos/#step-6-connect-your-home-assistant)

**🐧 Linux**

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

**Claude Desktop** — free, via the community build:

- Install the community
[Claude Desktop for Linux](https://github.com/aaddrick/claude-desktop-debian)build and sign in with a free[claude.ai](https://claude.ai)account - Open
**Terminal** and run:

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

- Restart Claude Desktop, then ask:
**"Can you see my Home Assistant?"**

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

- Install Claude Code:
`curl -fsSL https://claude.ai/install.sh | bash`

- Configure ha-mcp, then run
`claude`

:

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

- Start
`claude`

, run`/mcp`

to confirm, then ask:**"Can you see my Home Assistant?"**

**🪟 Windows**

- Go to
[claude.ai](https://claude.ai)and sign in (or create a free account) - Open
**Windows PowerShell**(from Start menu) and run:

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

[Download Claude Desktop](https://claude.ai/download)(or restart: File → Exit)- Ask Claude:
**"Can you see my Home Assistant?"**

You're now connected to the demo environment! [Connect your own Home Assistant →](https://homeassistant-ai.github.io/ha-mcp/guide-windows/#step-6-connect-your-home-assistant)

**🏠 Home Assistant OS (Add-on)**

-
Add the repository to your Home Assistant instance:

-
Install

**"Home Assistant MCP Server"** from the Add-on Store and wait for it to complete -
Click

**Start**, then open the** Logs**tab to find your unique MCP URL -
Configure your AI client with that URL

No token or credential setup needed — the add-on connects to Home Assistant automatically.

**🌐 Remote Access (Nabu Casa / Webhook Proxy)**

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.

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

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

- Configure your AI client with that URL

For other remote access methods (Cloudflare Tunnel, custom reverse proxy), see the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/).

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

Having issues? Check the [FAQ & Troubleshooting](https://homeassistant-ai.github.io/ha-mcp/faq/)

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.

| 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, add-ons, device registry |
🔒 Safety |
Read Only Mode toggle, per-tool enable/disable, tool security policies (user approval), automatic edit backups |

**Complete Tool List (84 tools)**

| Category | Tools |
|---|---|
Add-ons |
`ha_get_addon` , `ha_manage_addon` |
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_get_blueprint` , `ha_import_blueprint` |
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` |
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_enabled` |
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` |
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_set_yaml` (beta), `ha_get_updates` , `ha_manage_backup` , `ha_manage_custom_tool` (beta), `ha_manage_theme` , `ha_reload_core` , `ha_restart` |
Todo Lists |
`ha_get_todo` , `ha_remove_todo_item` , `ha_set_todo_item` |
Utilities |
`ha_eval_template` , `ha_install_mcp_tools` (beta), `ha_report_issue` |
Zones |
`ha_get_zone` , `ha_remove_zone` , `ha_set_zone` |

Home Assistant ships its own [MCP Server integration](https://www.home-assistant.io/integrations/mcp_server/). 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, add-ons, 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.

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

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

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`

.

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 **Home Assistant MCP Server Custom Component**.

On **Home Assistant OS / Supervised**, the integration offers to add the add-on repository and install and start the **Home Assistant MCP Server** add-on for you — no need to add the add-on repository by hand. On **Container / Core** installs (no Supervisor) there is no add-on; run the server via Docker or pip and the integration just sets up the file/YAML services.

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.

This server gives your AI agent tools to control Home Assistant. For better configurations, pair it with [Home Assistant Agent Skills](https://github.com/homeassistant-ai/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](https://modelcontextprotocol.io/docs/concepts/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](https://github.com/homeassistant-ai/skills) for instructions.

By default, the full tool catalog (~86 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 86 tools eats ~46K tokens of idle context. To address that, the server ships with a **search-based discovery mode** built on top of FastMCP's BM25 search transform.

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:

| Tool | Purpose |
|---|---|
`ha_search_tools` |
BM25 keyword search across all tools. Returns name, description, parameters, and annotations (`readOnlyHint` / `destructiveHint` ) so the agent can pick the right one. |
`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.

| Setting | Default | Description |
|---|---|---|
`ENABLE_TOOL_SEARCH` |
`false` |
Replace full tool catalog with search-based discovery (~46K → ~5K idle tokens). |
`TOOL_SEARCH_MAX_RESULTS` |
`5` |
Max results returned by `ha_search_tools` (range 2–10). |
`PINNED_TOOLS` |
empty | Comma-separated tool names to keep always visible. The web settings UI is the primary way to manage this. |

**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 86.
**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 itscachedtool list until it re-fetches. Restarting the add-on or Home Assistant doesnotrefresh 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](/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon/DOCS.md#enable_tool_search) along with the in-add-on settings UI for fine-grained tool enable/disable/pin.

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.

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](/homeassistant-ai/ha-mcp/blob/master/PRIVACY.md).

This project is licensed under the MIT License - see the [LICENSE](/homeassistant-ai/ha-mcp/blob/master/LICENSE) file for details.

: Amazing smart home platform (!)[Home Assistant](https://home-assistant.io/): Excellent MCP server framework[FastMCP](https://github.com/jlowin/fastmcp): Standardized AI-application communication[Model Context Protocol](https://modelcontextprotocol.io/): AI-powered coding assistant[Claude Code](https://github.com/anthropics/claude-code): Argument-path predicate DSL shape ([PolicyLayer](https://policylayer.com/)`args.domain in [...]`

with`eq`

/`in`

/`regex`

/`contains`

/`exists`

/...) inspired the per-tool approval rule schema (#966).

— Project creator.[@julienld](https://github.com/julienld)— Core maintainer.[@sergeykad](https://github.com/sergeykad)— Core maintainer.[@kingpanther13](https://github.com/kingpanther13)— Core maintainer.[@Patch76](https://github.com/Patch76)

— Explicit[@bigeric08](https://github.com/bigeric08)`mcp`

dependency for protocol version 2025-11-25 support.— Support for[@airlabno](https://github.com/airlabno)`data`

field in schedule time blocks.— Codex Desktop UI MCP quick setup guide.[@ryphez](https://github.com/ryphez)— Entity registry tools ([@Danm72](https://github.com/Danm72)`ha_set_entity`

,`ha_get_entity`

) for managing entity properties.— SOCKS proxy support.[@Raygooo](https://github.com/Raygooo)— Integration & entity management tools (enable/disable/delete); person/zone/tag config store routing.[@cj-elevate](https://github.com/cj-elevate)— Beta testing.[@maxperron](https://github.com/maxperron)— Windows UV setup guide.[@kingbear2](https://github.com/kingbear2)— Financial support via[@konradwalsh](https://github.com/konradwalsh)[GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕— Area resolution via device registry in[@knowald](https://github.com/knowald)`ha_get_system_overview`

for entities assigned through their parent device. Financial support via[GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕— Per-client WebSocket credentials in OAuth mode, fixing WebSocket tool failures.[@zorrobyte](https://github.com/zorrobyte)— Fixed[@deanbenson](https://github.com/deanbenson)`ha_deep_search`

timeout on large Home Assistant instances with many automations.— Config entry options flow tools (initial design, #590).[@saphid](https://github.com/saphid)— Fix menu-based config entry flows for group helpers (#647).[@adraguidev](https://github.com/adraguidev)— Integration options inspection ([@transportrefer](https://github.com/transportrefer)`ha_get_integration`

schema support, #689).— Fix blueprint import missing save step.[@teh-hippo](https://github.com/teh-hippo)— Documentation fix.[@smenzer](https://github.com/smenzer)— REST API for config entry deletion.[@The-Greg-O](https://github.com/The-Greg-O)— Responsible disclosure: python_transform sandbox missing call target validation.[@restriction](https://github.com/restriction)— Diagnostic and health monitoring tools concept (#675), inspiring system/error logs, repairs, and ZHA radio metrics integration.[@lcrostarosa](https://github.com/lcrostarosa)— Copilot CLI support in the installation wizard; replaced placeholder logo SVGs with real brand icons on the documentation site.[@roysha1](https://github.com/roysha1)— Fix add-on stats endpoint ([@teancom](https://github.com/teancom)`/addons/{slug}/stats`

).— Category support for automations, scripts, and scenes.[@TomasDJo](https://github.com/TomasDJo)—[@bzelch](https://github.com/bzelch)`python_transform`

support for automations and scripts.— Windows installer improvements: removed unused variable and fixed terminal closing after install.[@gcormier](https://github.com/gcormier)— Feature flags for[@ekobres](https://github.com/ekobres)`HAMCP_ENABLE_FILESYSTEM_TOOLS`

and`HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION`

in the add-on config, with beta tagging in source and docs.— Financial support via[@w3z315](https://github.com/w3z315)[GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕— Added OpenCode (by Anomaly) as a selectable AI client in the setup wizard, with both stdio and streamable HTTP support.[@griffinmartin](https://github.com/griffinmartin)— Fixed addon API calls to route through HA Core ingress proxy instead of direct container connections, fixing[@hhopke](https://github.com/hhopke)`ha_manage_addon`

proxy mode on addon installs.— JMESPath middleware exploration (#1147) whose review-time token-measurement data informed the design of #1199 and #1225.[@tomwilkie](https://github.com/tomwilkie)—[@SealKan](https://github.com/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).— Cached YAML instance to prevent CPU spikes during bulk edits (#1371).[@KarelTestSpecial](https://github.com/KarelTestSpecial)— HA brand assets for custom integration (#1317).[@corgan2222](https://github.com/corgan2222)— Progress emission via FastMCP[@drseanwing](https://github.com/drseanwing)`Context`

in long-running tools (#1124); tool-discovery / categorized-search docs (#1123).— Config subentry support (#1393) and Assist pipeline management tool (#1392).[@fnordpig](https://github.com/fnordpig)—[@paul43210](https://github.com/paul43210)`array_patch`

mode in`ha_manage_addon`

for atomic GET-modify-POST (#1063).— Filed #966 proposing tool security policies; pointed to PolicyLayer's MCP-security work as prior art that inspired the predicate DSL shape.[@L1AD](https://github.com/L1AD)— Updated stale Home Assistant Advanced Mode references after HA 2026.6 made formerly advanced options available by default (#1533).[@nightcityblade](https://github.com/nightcityblade)— Financial support via[@emmelutzer](https://github.com/emmelutzer)[GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕

— Ask questions, share ideas[GitHub Discussions](https://github.com/homeassistant-ai/ha-mcp/discussions)— Report bugs, request features, or suggest tool behavior improvements[Issue Tracker](https://github.com/homeassistant-ai/ha-mcp/issues)