# Ha Mcp Integration > HA-MCP Custom Component - HACS distribution mirror of homeassistant-ai/ha-mcp (integration only) - **Type:** MCP server - **Install:** `agentstack add mcp-homeassistant-ai-ha-mcp-integration` - **Verified:** Pending review - **Seller:** [homeassistant-ai](https://agentstack.voostack.com/s/homeassistant-ai) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [homeassistant-ai](https://github.com/homeassistant-ai) - **Source:** https://github.com/homeassistant-ai/ha-mcp-integration ## Install ```sh agentstack add mcp-homeassistant-ai-ha-mcp-integration ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # HA-MCP Custom Component HACS distribution repository for the ha-mcp custom integration. The source of truth is the main repository - [homeassistant-ai/ha-mcp](https://github.com/homeassistant-ai/ha-mcp) - which syncs this repository automatically. - **Stable**: install the latest release (default in HACS). - **Development**: enable this repository's **Pre-release** switch in HACS (an entity HACS creates per downloaded repository, disabled by default) to receive `-dev.N` pre-release builds. Their new features may require a newer server and only become fully usable with the next stable release. Please open issues and pull requests on the [main repository](https://github.com/homeassistant-ai/ha-mcp/issues) - this mirror carries no hand-made changes. --- > **Breaking change (v7.3.0):** `ha_config_set_yaml` has been moved to [beta](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/beta.md). # The Unofficial and Awesome Home Assistant MCP Server 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. --- --- ## ๐Ÿš€ 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):** [](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp-integration&category=integration) **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:///api/webhook/` through Nabu Casa or any reverse proxy already pointed at Home Assistant (locally, `http://:8123/api/webhook/`). For clients on the same network, the server is also reachable directly at `http://:9584/private_`. - **Replaces other install methods:** the in-process server is a complete, standalone ha-mcp install โ€” it takes the place of the 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, add-on, Docker, or stdio). [Full in-process server documentation โ†’](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/in-process-server.md) ยท [Setup Wizard for client-specific config โ†’](https://homeassistant-ai.github.io/ha-mcp/setup/) ### ๐Ÿ  Home Assistant App (add-on) Prefer to run ha-mcp as a Home Assistant **app / add-on**? On **Home Assistant OS** and **Supervised** installs it is a close second โ€” no access token to manage, and it works with Claude Desktop, Claude.ai, ChatGPT, and any other MCP client on your local network or configured for remote access. 1. Add the repository to your Home Assistant instance: [](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fhomeassistant-ai%2Fha-mcp) If that opens the App Store without an add-repository dialog (a [known Home Assistant issue](https://github.com/home-assistant/my.home-assistant.io/issues/698)), add it manually: **App Store โ†’ โ‹ฎ โ†’ Repositories**, then paste `https://github.com/homeassistant-ai/ha-mcp`. 2. Install **"Home Assistant MCP Server"** from the App Store and click **Start**. *(Home Assistant 2026.2 renamed "Add-ons" to "Apps"; on older versions this is the Add-on Store.)* 3. Open the **Logs** tab to find your unique MCP URL. 4. Connect your AI client to that URL โ€” **no token or credential setup needed**. [Full add-on documentation โ†’](https://github.com/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon/DOCS.md) > โš ๏ธ **Configure exactly one install method per client.** The custom component, the add-on, Docker/PyPI, and local stdio are independent ways to run the same server โ€” pick one and point your AI client at that single URL. Keeping two entries for the same server in one client (for example a local `uvx ha-mcp@latest` entry with `HOMEASSISTANT_URL` / `HOMEASSISTANT_TOKEN` alongside an add-on or component URL) is a known cause of connection hangs. ### Other install methods These run the server outside Home Assistant โ€” useful for **Container** / **Core** installs (which can't run add-ons) or a separate host. The [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) generates the exact client-specific config for each. - **Docker (HTTP server):** run `ghcr.io/homeassistant-ai/ha-mcp` in HTTP mode, pointed at your Home Assistant URL and a long-lived token, and connect your client to its secret URL. See the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) for the full command and per-client config. - **PyPI / uvx (HTTP server):** run the published `ha-mcp` package with `uvx ha-mcp@latest` (or pip) as a streamable-HTTP server the same way. Details in the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/). - **Local stdio (not recommended):** runs ha-mcp on your own machine over stdio. The one-command installers in the **Demo server** section below use this path; the [Setup Wizard](https://homeassistant-ai.github.io/ha-mcp/setup/) covers connecting it to your own Home Assistant. > โš ๏ธ **stdio has known transport issues.** The stdio transport has connection problems that streamable HTTP does not ([#1713](https://github.com/homeassistant-ai/ha-mcp/issues/1713)). It is recommended only for demo/testing tinkering โ€” for a real setup, use the custom component or an HTTP method above. ๐ŸŒ Remote access (Nabu Casa / Webhook Proxy add-on / OpenAI Tunnel) > **Using the HA-MCP custom component?** You do not need the **Webhook Proxy** โ€” the component has its own built-in webhook for remote access (see the **Get Started** quick start at the top). The proxy is for the **add-on** (it can also front another external server via its `mcp_server_url` option). The **OpenAI Tunnel** below is different: it applies to **any** install method when Home Assistant isn't publicly reachable at all (no Nabu Casa or reverse 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](https://homeassistant-ai.github.io/ha-mcp/setup/). **ChatGPT / Codex behind a firewall (OpenAI Tunnel).** ChatGPT connectors normally require a publicly reachable URL. If you can't (or don't want to) expose one, the community [OpenAI Tunnel for HA-MCP](https://github.com/norpol/hass-codex-tunnel-mcp) integration by [@norpol](https://github.com/norpol) runs OpenAI's [`tunnel-client`](https://github.com/openai/tunnel-client) inside Home Assistant and connects your local MCP server URL to an OpenAI-hosted tunnel over an outbound-only connection โ€” no port forwarding, reverse proxy, or public URL. Point it at your ha-mcp URL, then attach the ChatGPT connector to the same tunnel ID. See the [FAQ entry](https://homeassistant-ai.github.io/ha-mcp/faq/#openai-tunnel) and [#1811](https://github.com/homeassistant-ai/ha-mcp/issues/1811). [Webhook proxy documentation โ†’](https://github.com/homeassistant-ai/ha-mcp/blob/master/homeassistant-addon-webhook-proxy/DOCS.md) ### ๐Ÿงช Demo server (Windows / macOS / Linux) Want to try ha-mcp before connecting your own Home Assistant? *No paid subscription required.* These one-command scripts set up a local **stdio** connection to a hosted **demo** environment so you can see it working in a few minutes. Each script's **Connect your own Home Assistant** link then shows how to point it at your instance. ๐ŸŽ macOS 1. Go to [claude.ai](https://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](https://claude.ai/download) (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 โ†’](https://homeassistant-ai.github.io/ha-mcp/guide-macos/#step-6-connect-your-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](https://github.com/aaddrick/claude-desktop-debian) build and sign in with a free [claude.ai](https://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 โ†’](https://homeassistant-ai.github.io/ha-mcp/guide-linux/) ๐ŸชŸ Windows 1. Go to [claude.ai](https://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](https://claude.ai/download) (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 โ†’](https://homeassistant-ai.github.io/ha-mcp/guide-windows/#step-6-connect-your-home-assistant) ### ๐Ÿง™ Setup Wizard for 15+ clients **Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor, and more.** Having issues? Check the **[FAQ & Troubleshooting](https://homeassistant-ai.github.io/ha-mcp/faq/)** --- ## ๐Ÿ’ฌ 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 (87 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` | | **Developer** | `ha_dev_manage_server`, `ha_dev_manage_settings` | | **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` | | **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` | | **Matter** | `ha_manage_radio` | | **Scenes** | `ha_config_get_scene`, `ha_config_remove_scene`, ` โ€ฆ ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [homeassistant-ai](https://github.com/homeassistant-ai) - **Source:** [homeassistant-ai/ha-mcp-integration](https://github.com/homeassistant-ai/ha-mcp-integration) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: flagged โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-homeassistant-ai-ha-mcp-integration - Seller: https://agentstack.voostack.com/s/homeassistant-ai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.