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

The Unofficial and Awesome Home Assistant MCP Server

<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

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:

1. Install the HA-MCP Custom Component from HACS — click the badge above, or in HACS open Integrations → ⋮ → Custom repositories, add https://github.com/homeassistant-ai/ha-mcp-integration (category: Integration), then Download.
2. Restart Home Assistant.
3. Go to Settings → Devices & Services → Add Integration, search for HA-MCP Custom Component, choose HA-MCP Server, and click Submit. Creating the entry starts the server.
4. Copy the connect URL from the entry's Configure screen (Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure) — it is also printed in the Home Assistant log. A notification confirms the server started and points you there.
5. Paste that URL into your AI client — done.

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

• Replaces other install methods: the in-process server is a complete, standalone ha-mcp install — it takes the place of the app (add-on), Docker, and uvx/PyPI (stdio) methods. Run only one; do not run the in-process server alongside another install.
• Local only? Turn off Remote access via webhook in the entry options — no webhook is registered at all, while the direct port and sidebar panel keep working.
• Settings panel: while the server runs, an admin-only HA-MCP panel appears in the Home Assistant sidebar for managing tools, feature flags, backups, and themes.
• Optional authentication: set Webhook authentication to ha_auth to require a Home Assistant account sign-in instead of using the secret URL as the credential.
• Manual install (no HACS): copy 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).