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.aiand 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(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 →
🐧 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 Linuxbuild and sign in with a freeclaude.aiaccount - 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.aiand 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(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 →
🏠 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.
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:
| 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. 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 — 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 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.
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 (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 ; 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.TogglingENABLE_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 returnUnknown 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.
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 beforehandNo 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.
: Amazing smart home platform (!)Home Assistant: Excellent MCP server frameworkFastMCP: Standardized AI-application communicationModel Context Protocol: AI-powered coding assistantClaude Code: Argument-path predicate DSL shape (PolicyLayerargs.domain in [...]
witheq
/in
/regex
/contains
/exists
/...) inspired the per-tool approval rule schema (#966).
— Project creator.@julienld— Core maintainer.@sergeykad— Core maintainer.@kingpanther13— Core maintainer.@Patch76
— Explicit@bigeric08mcp
dependency for protocol version 2025-11-25 support.— Support for@airlabnodata
field in schedule time blocks.— Codex Desktop UI MCP quick setup guide.@ryphez— Entity registry tools (@Danm72ha_set_entity
,ha_get_entity
) for managing entity properties.— SOCKS proxy support.@Raygooo— Integration & entity management tools (enable/disable/delete); person/zone/tag config store routing.@cj-elevate— Beta testing.@maxperron— Windows UV setup guide.@kingbear2— Financial support via@konradwalshGitHub Sponsors. Thank you! ☕— Area resolution via device registry in@knowaldha_get_system_overview
for entities assigned through their parent device. Financial support viaGitHub Sponsors. Thank you! ☕— Per-client WebSocket credentials in OAuth mode, fixing WebSocket tool failures.@zorrobyte— Fixed@deanbensonha_deep_search
timeout on large Home Assistant instances with many automations.— Config entry options flow tools (initial design, #590).@saphid— Fix menu-based config entry flows for group helpers (#647).@adraguidev— Integration options inspection (@transportreferha_get_integration
schema support, #689).— Fix blueprint import missing save step.@teh-hippo— Documentation fix.@smenzer— REST API for config entry deletion.@The-Greg-O— Responsible disclosure: python_transform sandbox missing call target validation.@restriction— Diagnostic and health monitoring tools concept (#675), inspiring system/error logs, repairs, and ZHA radio metrics integration.@lcrostarosa— Copilot CLI support in the installation wizard; replaced placeholder logo SVGs with real brand icons on the documentation site.@roysha1— Fix add-on stats endpoint (@teancom/addons/{slug}/stats
).— Category support for automations, scripts, and scenes.@TomasDJo—@bzelchpython_transform
support for automations and scripts.— Windows installer improvements: removed unused variable and fixed terminal closing after install.@gcormier— Feature flags for@ekobresHAMCP_ENABLE_FILESYSTEM_TOOLS
andHAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION
in the add-on config, with beta tagging in source and docs.— Financial support via@w3z315GitHub Sponsors. Thank you! ☕— Added OpenCode (by Anomaly) as a selectable AI client in the setup wizard, with both stdio and streamable HTTP support.@griffinmartin— Fixed addon API calls to route through HA Core ingress proxy instead of direct container connections, fixing@hhopkeha_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—@SealKanfields=
/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— HA brand assets for custom integration (#1317).@corgan2222— Progress emission via FastMCP@drseanwingContext
in long-running tools (#1124); tool-discovery / categorized-search docs (#1123).— Config subentry support (#1393) and Assist pipeline management tool (#1392).@fnordpig—@paul43210array_patch
mode inha_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— Updated stale Home Assistant Advanced Mode references after HA 2026.6 made formerly advanced options available by default (#1533).@nightcityblade— Financial support via@emmelutzerGitHub Sponsors. Thank you! ☕
— Ask questions, share ideasGitHub Discussions— Report bugs, request features, or suggest tool behavior improvementsIssue Tracker