github.com/homeassistant-ai/ha-mcp @v7.9.0 sqlite

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

# The Unofficial and Awesome Home Assistant MCP Server

<img src="https://img.shields.io/badge/tools-84-blue" alt="95+ Tools">
<a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
<a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
<a href="https://github.com/homeassistant-ai/ha-mcp/raw/v7.9.0/LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>



<a href="https://github.com/homeassistant-ai/ha-mcp/commits/master"><img src="https://img.shields.io/github/commit-activity/m/homeassistant-ai/ha-mcp.svg" alt="Activity"></a>
<a href="https://github.com/jlowin/fastmcp"><img src="https://img.shields.io/badge/Built%20with-FastMCP-purple" alt="Built with FastMCP"></a>
<img src="https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fhomeassistant-ai%2Fha-mcp%2Fmaster%2Fpyproject.toml" alt="Python Version">
<a href="https://github.com/sponsors/julienld"><img src="https://img.shields.io/badge/GitHub_Sponsors-☕-blueviolet" alt="GitHub Sponsors"></a>
<a href="https://homeassistant-ai.github.io/ha-mcp/"><img src="https://img.shields.io/badge/Website-docs-teal" alt="Website"></a>







<em>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.</em>

---

---

🚀 Get Started

Full guide to get you started with Claude Desktop (~10 min)

No paid subscription required. Click on your operating system:

        

Quick install (~5 min)

🍎 macOS

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 →

🐧 Linux

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 →

🪟 Windows

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 →

🏠 Home Assistant OS (Add-on)

1. Add the repository to your Home Assistant instance:

1. Install "Home Assistant MCP Server" from the Add-on Store and wait for it to complete
2. Click Start, then open the Logs tab to find your unique MCP URL
3. Configure your AI client with that URL

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

Full add-on documentation →

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

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

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.

---

✨ Features

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

---

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

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.

---

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

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