ha-mcp connects an MCP client to Home Assistant so the agent can read states, call services, and edit Home Assistant configuration. It supports multiple install paths, including a Home Assistant custom component, a Home Assistant add-on, Docker, and local stdio.
Builders who want their agent to control and maintain Home Assistant instead of just reading device state.
You can ask an agent to create automations, update dashboards, inspect logs, and manage your smart home from one chat.
Find entities, read current state, call services, control devices in bulk, and inspect system overviews.
Create, update, and remove automations, scripts, scenes, helpers, groups, zones, and dashboard content.
Read history, statistics, logs, automation traces, and camera snapshots to understand what went wrong.
Handle backups, updates, apps, HACS, device and entity registry, themes, security policies, and core restart actions.
With the custom component and beta flags, the server can read, write, list, and delete allowed files and edit `configuration.yaml` safely.
Run it as a Home Assistant custom component, add-on, Docker server, or stdio client, with webhook and OIDC options for remote access.
Serves Home Assistant agent skills as MCP resources and provides `ha_get_skill_guide` for tool-only clients.
MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx
Breaking change (v7.3.0):
ha_config_set_yamlhas 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.
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:
https://github.com/homeassistant-ai/ha-mcp-integration (category: Integration), then Download.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>.
ha_auth to require a Home Assistant account sign-in instead of using the secret URL as the credential.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.
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.
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.)
Open the Logs tab to find your unique MCP URL.
Connect your AI client to that URL — no token or credential setup needed.
⚠️ 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@latestentry withHOMEASSISTANT_URL/HOMEASSISTANT_TOKENalongside 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, 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.
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_urloption). 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.
MCP Server URL (remote): https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx
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.
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.
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh
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:
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
Claude Code — official CLI, requires a paid Claude plan:
curl -fsSL https://claude.ai/install.sh | bashclaude:
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code
claude, run /mcp to confirm, then ask: "Can you see my Home Assistant?"irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex
You're now connected to the demo environment! Connect your own Home Assistant →
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, apps, device registry |
| 🔒 Safety | Read Only Mode toggle, per-tool enable/disable, tool security policies (user approval), automatic edit backups |
| 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 |
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.
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:
| 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 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 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
Sign in to join the discussion.
No comments yet. Be the first to say what this is good for.
High-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code
Git-native persistent memory for AI coding agents. Implements Google OKF v0.2 with sub-300µs in-memory BM25 search, embedded MCP server, and progressive disclosure. Slashes token bloat by 80% with zero external databases or dependencies. Built in pure Go.
Local-first code intelligence graph for MCP and CLI. Builds a persistent map of your codebase so AI coding tools read only what matters, with benchmarked context reductions on reviews and large-repo workflows.
Stop your AI from making things up — it proposes, deterministic tools decide, every claim checked against ground truth with evidence. Grounded facts and context survive resets. Reverse engineering is the proving ground. MCP server + CLI.
20 MB lightweight cross-platform database client for 90+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具，支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90+ 数据库，提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。