Is Home Assistant MCP free?

Yes, Home Assistant MCP is free to use.

How do I install Home Assistant MCP?

Home Assistant MCP is a local plugin. Install it using PyPI package: ha-mcp and add the generated configuration snippet to your AI app's MCP config file. Then restart your AI app.

What AI apps work with Home Assistant MCP?

Home Assistant MCP uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

Home Assistant MCP MCP Server

by User

OtherModerate7.5Local

Free

The Unofficial and Awesome Home Assistant MCP Server

About

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.

Security Report

7.5

Moderate7.5Low Risk

This is a Home Assistant MCP server that provides comprehensive smart home control capabilities. The code follows good security practices with proper environment variable handling, input validation, and authorization patterns. While it requires broad permissions to function as intended for smart home automation, these permissions align with its stated purpose. Package verification found 1 issue.

4 tools verified · Open access · 5 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

HTTP Network Access

Connects to external APIs or services over the internet.

network_websocket

Check that this permission is expected for this type of plugin.

env_vars

Check that this permission is expected for this type of plugin.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "home-assistant-mcp": {
      "args": [
        "-y",
        "site"
      ],
      "command": "npx"
    }
  }
}

Documentation

View on GitHub

From the project's GitHub README.

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

The Unofficial and Awesome Home Assistant MCP Server

Demo with Claude Desktop

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

Go to 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 (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 →

Go to 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 (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 →

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.

Full add-on documentation →

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.

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

Category	Tools
Add-ons	`ha_get_addon`, `ha_manage_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` (beta), `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`

🔌 Custom Component (ha_mcp_tools)

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.

Install using HACS (recommended)

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.

Install manually

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.

🧠 Better Results with Agent Skills

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.

Bundled Skills (built-in)

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.

🧪 Dev Channel

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.

🤝 Contributing

For development setup, testing instructions, and contribution guidelines, see CONTRIBUTING.md.

For comprehensive testing documentation, see tests/README.md.

🔒 Privacy

Ha-mcp runs locally on your machine. Your smart home data stays on your network.

Configurable telemetry — optional anonymous usage stats
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.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Home Assistant: Amazing smart home platform (!)
FastMCP: Excellent MCP server framework
Model Context Protocol: Standardized AI-application communication
Claude Code: AI-powered coding assistant

👥 Contributors

Maintainers

@julienld — Project creator & core maintainer.
@sergeykad — Core maintainer.
@kingpanther13 — Core maintainer.

Contributors

@bigeric08 — Explicit mcp dependency for protocol version 2025-11-25 support.
@airlabno — Support for data field in schedule time blocks.
@ryphez — Codex Desktop UI MCP quick setup guide.
@Danm72 — Entity registry tools (ha_set_entity, ha_get_entity) for managing entity properties.
@Raygooo — SOCKS proxy support.
@cj-elevate — Integration & entity management tools (enable/disable/delete); person/zone/tag config store routing.
@maxperron — Beta testing.
@kingbear2 — Windows UV setup guide.
@konradwalsh — Financial support via GitHub Sponsors. Thank you! ☕
@knowald — Area resolution via device registry in ha_get_system_overview for entities assigned through their parent device.
@zorrobyte — Per-client WebSocket credentials in OAuth mode, fixing WebSocket tool failures.
@deanbenson — Fixed ha_deep_search timeout on large Home Assistant instances with many automations.
@saphid — Config entry options flow tools (initial design, #590).
@adraguidev — Fix menu-based config entry flows for group helpers (#647).
@transportrefer — Integration options inspection (ha_get_integration schema support, #689).
@teh-hippo — Fix blueprint import missing save step.
@smenzer — Documentation fix.
@The-Greg-O — REST API for config entry deletion.
@restriction — Responsible disclosure: python_transform sandbox missing call target validation.
@lcrostarosa — Diagnostic and health monitoring tools concept (#675), inspiring system/error logs, repairs, and ZHA radio metrics integration.
@roysha1 — Copilot CLI support in the installation wizard.
@Patch76 — ha_remove_entity tool, history/statistics pagination and validation, docs sync automation, docstring guidelines, dashboard tool consolidation.
@teancom — Fix add-on stats endpoint (/addons/{slug}/stats).
@TomasDJo — Category support for automations, scripts, and scenes.
@bzelch — python_transform support for automations and scripts.