Pre-release

This release is a pre-release and may not be stable for production use.

⚠️ Breaking change in OAuth (beta) mode — v7.0.0 requires HOMEASSISTANT_URL to be set server-side. See issue #749 for migration instructions.

The Unofficial and Awesome Home Assistant MCP Server

95+ Tools
Python Version

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.

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)

🍎 macOS

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 →

🪟 Windows

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 →

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

Full add-on 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

🛠️ Complete Tool List (96 tools)

Category	Tools
Search & Discovery	`ha_search_entities`, `ha_deep_search`, `ha_get_overview`, `ha_get_state`
Service & Device Control	`ha_call_service`, `ha_bulk_control`, `ha_get_operation_status`, `ha_get_bulk_status`, `ha_list_services`
Automations	`ha_config_get_automation`, `ha_config_set_automation`, `ha_config_remove_automation`
Scripts	`ha_config_get_script`, `ha_config_set_script`, `ha_config_remove_script`
Helper Entities	`ha_config_list_helpers`, `ha_config_set_helper`, `ha_config_remove_helper`
Dashboards	`ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard`, `ha_get_dashboard_guide`, `ha_get_card_documentation`
Areas & Floors	`ha_config_list_areas`, `ha_config_set_area`, `ha_config_remove_area`, `ha_config_list_floors`, `ha_config_set_floor`, `ha_config_remove_floor`
Labels	`ha_config_get_label`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels`
Zones	`ha_get_zone`, `ha_set_zone`, `ha_remove_zone`
Groups	`ha_config_list_groups`, `ha_config_set_group`, `ha_config_remove_group`
Todo Lists	`ha_get_todo`, `ha_add_todo_item`, `ha_update_todo_item`, `ha_remove_todo_item`
Calendar	`ha_config_get_calendar_events`, `ha_config_set_calendar_event`, `ha_config_remove_calendar_event`
Blueprints	`ha_list_blueprints`, `ha_get_blueprint`, `ha_import_blueprint`
Device Registry	`ha_get_device`, `ha_update_device`, `ha_remove_device`, `ha_rename_entity`
ZHA & Integrations	`ha_get_zha_devices`, `ha_get_entity_integration_source`
Add-ons	`ha_get_addon`
Camera	`ha_get_camera_image`
History & Statistics	`ha_get_history`, `ha_get_statistics`
Automation Traces	`ha_get_automation_traces`
System & Updates	`ha_check_config`, `ha_restart`, `ha_reload_core`, `ha_get_system_info`, `ha_get_system_health`, `ha_get_updates`
Backup & Restore	`ha_backup_create`, `ha_backup_restore`
Utility	`ha_get_logbook`, `ha_eval_template`, `ha_get_domain_docs`, `ha_get_integration`

🧠 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`	`false`	Also expose skills via `list_resources`/`read_resource` tools for clients that don't support MCP resources natively.

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).
@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).

💬 Community

GitHub Discussions — Ask questions, share ideas
Issue Tracker — Report bugs, request features, or suggest tool behavior improvements

⭐ Star History

Metadata

Release files for ha-mcp-dev 7.0.0.dev272

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ha-mcp-dev 7.0.0.dev272
File	Size	Uploaded
ha_mcp_dev-7.0.0.dev272.tar.gz	270.5 kB	Mar 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ha-mcp-dev 7.0.0.dev272
File	Interpreter	ABI	Platform	Reset
ha_mcp_dev-7.0.0.dev272-py3-none-any.whl 310.4 kB Mar 14, 2026	Python 3	none	any	Details

Total release size: 580.9 kB

Release files / ha_mcp_dev-7.0.0.dev272.tar.gz

Download URL	ha_mcp_dev-7.0.0.dev272.tar.gz
Size	270.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`a4273c594b8862ecc6c631e4f01057a3559806d7f325ecfefe284fb82186f5dc`
BLAKE2b-256 checksum How to use checksums	`dad6412f971f069f354d7a0ab06abf1eb13333a037fa53233872a1d6d509458a`
Upload date	Mar 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/homeassistant-ai/ha-mcp
Publishing commit: github.com/homeassistant-ai/ha-mcp/tree/51b9dca5548581ad079a67262fe1e617b18b0067

Workflow

Publishing configuration: github.com/homeassistant-ai/ha-mcp/blob/51b9dca5548581ad079a67262fe1e617b18b0067/.github/workflows/publish-dev.yml
Publishing logs: github.com/homeassistant-ai/ha-mcp/actions/runs/23085656043/attempts/1

Artifact

Subject: ha_mcp_dev-7.0.0.dev272.tar.gz
SHA-256 checksum: a4273c594b8862ecc6c631e4f01057a3559806d7f325ecfefe284fb82186f5dc Verifying attestations

Release files / ha_mcp_dev-7.0.0.dev272-py3-none-any.whl

Download URL	ha_mcp_dev-7.0.0.dev272-py3-none-any.whl
Size	310.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f68419d82740aa05e1477ea3df58c381332943c430811ef8133acd3a33b83a37`
BLAKE2b-256 checksum How to use checksums	`e5386c535ca5bf8ed3bef9feef6e3c0c4c29cbbb2db7d8aca45aed624c757861`
Upload date	Mar 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/homeassistant-ai/ha-mcp
Publishing commit: github.com/homeassistant-ai/ha-mcp/tree/51b9dca5548581ad079a67262fe1e617b18b0067

Workflow

Publishing configuration: github.com/homeassistant-ai/ha-mcp/blob/51b9dca5548581ad079a67262fe1e617b18b0067/.github/workflows/publish-dev.yml
Publishing logs: github.com/homeassistant-ai/ha-mcp/actions/runs/23085656043/attempts/1

Artifact

Subject: ha_mcp_dev-7.0.0.dev272-py3-none-any.whl
SHA-256 checksum: f68419d82740aa05e1477ea3df58c381332943c430811ef8133acd3a33b83a37 Verifying attestations