← Back to Setup

Home Assistant App (Add-on) Setup

Run ha-mcp inside Home Assistant OS — works with Claude Desktop and any MCP client

Runs on Home Assistant OS / Supervised. No access token to create or manage — the app handles the connection for you. (New here? The HA custom component is the recommended install and works on every installation type.)

One mode at a time

This is the app (add-on) setup. It is separate from the local/stdio setup in the Windows / macOS / Linux guides. If you already configured the local version (a Claude Desktop entry running uvx ha-mcp@latest with HOMEASSISTANT_URL and HOMEASSISTANT_TOKEN), remove that entry — the app replaces it and needs no token. Running both at once is a common cause of connection problems. More in the FAQ.

1

Add the ha-mcp repository

In Home Assistant, add the ha-mcp app repository:

Add the ha-mcp app (add-on) repository to your Home Assistant

Or paste the repository URL into Settings → Apps → App Store → ⋮ (top right) → Repositories: https://github.com/homeassistant-ai/ha-mcp

2

Install the app

Open Settings → Apps → App Store, find Home Assistant MCP Server, and install it.

Home Assistant 2026.2 renamed "Add-ons" to "Apps" — on older versions this is Settings → Add-ons → Add-on Store, and the app is the same "MCP Server".

3

Start it and copy the server URL

Start the app, then open its Logs tab (Settings → Apps → Home Assistant MCP Server → Logs — these are the app's logs, not the main HA logs).

Copy the MCP server URL from the log line — it looks like:

MCP Server URL: http://192.168.1.100:9583/private_zctpwlX7ZkIAr7oqdfLPxw

The app auto-discovers the HA connection, generates a secure secret path, and configures the token — no manual setup needed. Defaults: port 9583, 128-bit random secret path, persisted across restarts.

4

Connect Claude Desktop

Claude Desktop talks to MCP servers over stdio, so it reaches the app through mcp-proxy (run automatically via uvx). That needs uv on the computer running Claude Desktop:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
winget install --id=astral-sh.uv -e

Open Claude Desktop's config (Settings → Developer → Edit Config) and paste this, replacing the URL with the one from Step 3:

{
  "mcpServers": {
    "home-assistant": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "http://192.168.1.100:9583/private_zctpwlX7ZkIAr7oqdfLPxw"
      ]
    }
  }
}

No token goes here. The app already handles authentication behind the secret path in the URL. Do not add HOMEASSISTANT_URL, HOMEASSISTANT_TOKEN, or an env block — that is the local/stdio config, and pasting it alongside the app is a known cause of connection hangs.

Then restart Claude Desktop: File → Exit, then reopen.

Using a different client (Claude.ai, ChatGPT, Cursor, …)?

Clients that speak HTTP natively don't need mcp-proxy — they take the Step 3 URL directly. The Setup Wizard generates the exact config for each client.

The app serves Streamable HTTP, not SSE. A --transport sse config pointed at it returns a 405 and won't connect.

5

Test it

Ask your client:

Can you see my Home Assistant?

It should respond with entities from your Home Assistant.

6

Access it from outside your network (optional)

The URL from Step 3 only works on your local network. To reach the app from anywhere — for example from Claude.ai or ChatGPT, which need a public HTTPS URL — put it behind a secure tunnel or your existing reverse proxy.

The Setup Wizard walks through the remote options step by step: pick Remote (Internet), then Cloudflare Tunnel or Nabu Casa / Webhook Proxy.

7

Tip: the ha-mcp Settings page

The app ships a web settings page where you can enable, disable, and pin individual MCP tools, toggle feature flags and advanced (beta) settings, manage automatic backups, and review tool-approval requests.

Open it from the app's Open Web UI button, or ask Claude "how do I open the ha-mcp settings page?"

See the FAQ for every way to reach it and how to disable the settings server if you don't want it.

Having issues? See the FAQ & Troubleshooting Guide