The Unofficial and Awesome Home Assistant MCP Server
⚠️ Breaking change in OAuth mode (v7.0.0) — SetHOMEASSISTANT_URLserver-side. The consent form now accepts only the token. Migration guide →
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:
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | shYou're now connected to the demo environment! Connect your own Home Assistant →
irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iexYou're now connected to the demo environment! Connect your own Home Assistant →
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.
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.
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.
Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor, and more.
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 |
| Category | Tools |
|---|---|
| Add-ons | ha_call_addon_api, ha_get_addon |
| Areas & Floors | ha_config_list_areas, ha_config_list_floors, ha_config_remove_area, ha_config_remove_floor, ha_config_set_area, ha_config_set_floor |
| 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 |
| 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_update_device |
| Entity Registry | ha_get_entity_exposure, ha_get_entity, ha_remove_entity, ha_set_entity |
| Files | ha_delete_file, ha_list_files, ha_read_file, ha_write_file |
| Groups | ha_config_list_groups, ha_config_remove_group, ha_config_set_group |
| HACS | ha_hacs_add_repository, ha_hacs_download, ha_hacs_repository_info, ha_hacs_search |
| Helper Entities | ha_config_list_helpers, ha_config_remove_helper, ha_config_set_helper, ha_get_helper_schema, ha_set_config_entry_helper |
| History & Statistics | ha_get_automation_traces, ha_get_history, ha_get_logs |
| Integrations | ha_delete_config_entry, ha_get_integration, 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 |
| Scripts | ha_config_get_script, ha_config_remove_script, ha_config_set_script |
| Search & Discovery | ha_deep_search, ha_get_overview, ha_get_state, ha_search_entities |
| Service & Device Control | ha_bulk_control, ha_call_service, ha_get_operation_status, ha_list_services |
| System | ha_backup_create, ha_backup_restore, ha_check_config, ha_config_set_yaml, ha_get_system_health, ha_get_updates, 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, ha_report_issue |
| Zones | ha_get_zone, ha_remove_zone, ha_set_zone |
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 |
Safely add, replace, or remove top-level YAML keys in configuration.yaml and package files (automatic backup, validation, and config check) |
ha_list_files |
List files in allowed directories (www/, themes/, custom_templates/) |
ha_read_file |
Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) |
ha_write_file |
Write files to allowed directories |
ha_delete_file |
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 HA MCP Tools.
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.
| Setting | Default | Description |
|---|---|---|
ENABLE_SKILLS |
true |
Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
ENABLE_SKILLS_AS_TOOLS |
true |
Expose skills and doc resources via list_resources/read_resource tools. Resource-capable clients can set to false to reduce tool count. |
Skills can still be installed manually for clients that prefer local skill files — see the skills repo for instructions.
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.
For full details, see our Privacy Policy.
This project is licensed under the MIT License - see the LICENSE file for details.
mcp dependency for protocol version 2025-11-25 support.data field in schedule time blocks.ha_set_entity, ha_get_entity) for managing entity properties.ha_get_system_overview for entities assigned through their parent device.ha_deep_search timeout on large Home Assistant instances with many automations.ha_get_integration schema support, #689).ha_remove_entity tool, docs sync automation, and file-read deduplication in check_sync./addons/{slug}/stats).| Version | Changes | Urgency | Date |
|---|---|---|---|
| v7.3.0 | ### Added - Harden ha_config_set_yaml description and require justification ([#942](https://github.com/homeassistant-ai/ha-mcp/pull/942)) - Add python_transform support to automations and scripts ([#968](https://github.com/homeassistant-ai/ha-mcp/pull/968)) - **history**: Add offset pagination for history and statistics sources ([#964](https://github.com/homeassistant-ai/ha-mcp/pull/964)) - **site**: Redesign documentation site with professional visual identity ([#938](https://github.c | High | 4/15/2026 |
| v7.2.0 | ### Added - Add managed YAML config editing tool (ha_config_set_yaml) ([#827](https://github.com/homeassistant-ai/ha-mcp/pull/827)) - Tool explorer with taxonomy, auto-generated docs, and design mode ([#839](https://github.com/homeassistant-ai/ha-mcp/pull/839)) - Add generic add-on API proxy tool (ha_call_addon_api) ([#641](https://github.com/homeassistant-ai/ha-mcp/pull/641)) - Add support for automation/script/scene categories ([#677](https://github.com/homeassistant-ai/ha-mcp/pull/6 | Medium | 4/1/2026 |