Connect Claude to Home Assistant with MCP
Give Claude access to your smart home through Home Assistant's built-in MCP server. Pick a safe public path, then lock it to a dedicated read-only account.
How to connect Claude to Home Assistant with MCP
To connect Claude to Home Assistant with MCP, turn on Home Assistant's built-in Model Context Protocol integration and add its address to Claude as a custom connector. Claude then signs in through Home Assistant's own OAuth login. OAuth is the open standard for giving an app access without sharing your password. Home Assistant needs a public HTTPS address first. That address is most of the work, because Claude reaches your home from Anthropic's cloud, even when you use Claude Desktop.
MCP (Model Context Protocol) is an open standard that lets an AI client call tools on another server. Home Assistant has shipped its MCP Server integration since release 2025.2. Its tools can read the state of your home and, with the right options, control it. So the real decision is about security. Who can reach the address you open, and what is the account behind it allowed to do? If you are still deciding where MCP fits among the other ways to extend Claude, start with how MCP compares with agent skills and rules files.
This guide was checked against the Home Assistant, Anthropic, Tailscale, Caddy and Nabu Casa documentation on 15 November 2026. The current Home Assistant release that day was 2026.11.1. Several options below are only a few months old, so update Home Assistant before you start.
Why Claude needs Home Assistant on the public internet
Anthropic's help article on custom connectors says it directly: "Claude connects to your remote MCP server from Anthropic's cloud infrastructure, rather than from your local device." The Home Assistant docs say the same about the desktop app: "Claude connects to your MCP server from the cloud, also when you use Claude Desktop."
Two requirements follow from that. Your server must be reachable over the public internet from Anthropic's IP ranges. It must also answer on the standard HTTPS port, 443. So http://homeassistant.local:8123 can never work as a connector URL. Anthropic's servers cannot resolve a name that exists only on your home network, and port 8123 is not 443.
Claude Desktop also has a second mechanism. Local MCP servers listed in claude_desktop_config.json do use your local network. They are separate from connectors, and they are not available on claude.ai or in Cowork sessions that run in the cloud. The Home Assistant docs describe only the connector path for Claude Desktop, so this guide uses that path.
Claude Code is different. It runs on your own computer or server and opens the MCP connection itself, so the URL only has to be reachable from that machine. Home Assistant notes that "Claude Code connects to MCP servers over HTTPS only". A private HTTPS address inside your own network therefore works too. The difference between Tailscale Serve and Tailscale Funnel is exactly this choice: Serve gives a private HTTPS address on your tailnet, and Funnel gives a public one.
Custom connectors are available on the Free, Pro, Max, Ultra, Team and Enterprise plans. Free users are limited to one custom connector. That is one of the limits covered in what the Claude Free plan includes.
Turn on the MCP Server integration
- In Home Assistant, go to Settings > Devices & services and select Add Integration.
- Choose Model Context Protocol from the list and follow the on-screen steps.
- Go to Settings > System > AI. If the Model Context Protocol card shows an Enable button, select it.
- Copy the Main URL. Its path is
/api/mcp.
The full connector URL is your public hostname plus that path, for example https://ha.example.com/api/mcp. The hostname depends on the access path you choose further down.
What the main URL exposes by default
The main URL has three options, and they apply only to /api/mcp. Read them before you connect anything.
- Expose all AI tools is on by default. The main URL then exposes every set of tools, including sets that integrations add later. One set is called Home Assistant. The docs say it "can read all entities, logs, and history, and perform any action."
- Require an administrator account is on by default. When the main URL exposes the Home Assistant set, an administrator account is always required, whatever this switch says.
- Read-only is off by default. When you turn it on, the main URL only exposes tools that are marked as not changing anything, such as getting the current state of your home.
- Older setups keep two of these switches off. For Expose all AI tools, the docs say it "stays turned off so that your clients keep the tools you selected." The administrator switch "stays turned off so that your clients keep working." If your MCP Server entry is older than these options, open its options and check them.
Turn off Expose all AI tools to pick tool sets one at a time. The Device control set gives the AI the same tools as your voice assistant, and it "only accesses the entities you expose to voice assistants." The Home Assistant set has no such limit.
There are also separate URLs for single tool sets. /api/mcp/assist exposes only Device control. These URLs ignore the three options above. They are never read-only. All of them except the Device control URL require an administrator account.
Check what Device control can reach before you trust it. Assist exposes new entities by default, and that includes covers. The Home Assistant docs are specific: "Covers include garage doors and gates, so Home Assistant exposes them automatically too." Locks, alarm panels and scripts are not exposed automatically. Open the Assist exposure settings and remove any entity you would not want a chat window to open.
Use a dedicated account, not the owner
When you select Connect in Claude, you log in to Home Assistant in your browser. The access Claude receives belongs to the account you logged in with. If you log in as the owner, Claude acts as the owner, with every right the owner has.
Create a separate person in Home Assistant with its own login, and use it only for Claude. To revoke Claude's access later, you delete that one account, and your own login is not touched. Then pick one of two setups.
Narrow: Claude controls a few devices. Keep the account a normal user, not an administrator. In the main URL options, turn off Expose all AI tools, select only Device control, and turn off Require an administrator account. Claude can then reach only the voice-exposed entities. Turn on Read-only as well if Claude should only report state. You could use /api/mcp/assist instead, which needs no administrator. That URL ignores the Read-only switch, though.
Broad: Claude reads logs and history. The Home Assistant tool set always needs an administrator account. Make the dedicated account an administrator, keep it separate from the owner, and turn on Read-only. Claude can then read entities, logs and history. Tools that change something are not exposed.
During the Connect step, check which account you log in with. Doing that step in a private browser window makes it hard to reuse your owner session by mistake.
Do not rely on approval prompts in the client as your protection. In the connector flow, the Home Assistant docs say Claude asks for permission before calling any tools. Claude Code is different. From v2.1.283, auto mode is the starting permission mode for interactive terminal and VS Code sessions, and auto mode does not ask before every action. Home Assistant itself enforces the account's rights and the Read-only switch, whatever the client decides.
How should Claude's cloud reach Home Assistant?
The rest of this section is this guide's own threat model, worked out from what each service documents. None of these vendors says in its docs what its path does not protect against, so treat this section as reasoning, not as vendor claims.
Every path below has one thing in common: anyone who can reach the URL can reach Home Assistant's login page. So set up login protection first. In Settings > System > Network, in the HTTP server section, turn on Enable IP banning. Then set Login attempts before ban, which accepts 1 to 1000 and appears only when Unlimited login attempts is off. Behind any proxy or tunnel, also turn on Trust X-Forwarded-For and add the proxy's address to Trusted proxies. The Home Assistant docs warn: "Requests from reverse proxies are blocked if these options are not set." Before Home Assistant 2026.8, these settings were in the http: block of configuration.yaml.
Nabu Casa remote UI (Home Assistant Link)
Nabu Casa's service is now named Home Assistant Link (formerly Home Assistant Cloud). On 15 November 2026 its pricing page listed $6.50 USD per month or $65.00 USD per year, tax not included. It also listed a 31-day free trial that needs no card. Remote access is one of the listed benefits.
What it exposes: your whole Home Assistant web interface and login page, on a public HTTPS address. What it does not cover: a weak password on the account Claude uses, or a token that leaks from somewhere else. Nabu Casa's support site did not load while this guide was being written. Read their own documentation to learn what their relay can and cannot see.
Tailscale Funnel
Funnel routes traffic from the public internet to a local service, and Tailscale says it is available on all plans. It needs Tailscale v1.38.3 or later, MagicDNS, valid HTTPS certificates for your tailnet, and a funnel node attribute in your tailnet policy file. It can only listen on ports 443, 8443 and 10000. Port 443 is the one Claude needs. If those requirements are new to you, what Tailscale is and how a tailnet works explains them. On the machine that runs Home Assistant, run:
sudo tailscale funnel 8123Tailscale prints a public https://<machine>.<tailnet>.ts.net address that proxies to http://127.0.0.1:8123. Use that hostname in the connector URL. Add 127.0.0.1 to Trusted proxies in Home Assistant, because every request now comes from the local Tailscale proxy. The command runs in the foreground until you press Ctrl+C.
What it exposes: the whole Home Assistant port, to anyone on the internet. Funnel visitors do not need Tailscale, so your private tailnet gives them no extra barrier. Funnel traffic also has bandwidth limits that you cannot configure.
Cloudflare Tunnel
Cloudflare Tunnel uses an outbound-only connection. The cloudflared daemon inside your network connects out to Cloudflare, so you open no inbound port and need no public IP at home.
What it exposes: the hostname you publish, to the whole internet, unless you add rules in front of it. A rule that makes a person sign in at Cloudflare first must let Anthropic's published IP ranges through. Claude's cloud cannot fill in a login page, so its MCP requests would stop at Cloudflare. Add the address that cloudflared uses to reach Home Assistant to Trusted proxies.
A reverse proxy on a VPS
With this path, you control the server that faces the internet. A small VPS (virtual private server) with a public IP runs the reverse proxy, and it reaches Home Assistant at home over a private link such as a tailnet. Nothing at home is opened to the internet. You can also limit who reaches the proxy at all.
Anthropic publishes the IP addresses it uses for outbound requests, "for example, when making MCP tool calls to external servers." On 15 November 2026 the page listed two outbound IPv4 ranges in CIDR form, and no outbound IPv6 range. Copy the current ranges from Anthropic's IP address page on the day you set this up. The page also lists old addresses that are no longer in use, so take only the current outbound ones.
With Caddy installed on the VPS, /etc/caddy/Caddyfile can drop every connection that does not come from those ranges:
ha.example.com {
@blocked not remote_ip <anthropic-range-1> <anthropic-range-2> 203.0.113.25
abort @blocked
reverse_proxy 100.101.102.103:8123
}Replace <anthropic-range-1> and <anthropic-range-2> with the outbound IPv4 ranges from Anthropic's page, 203.0.113.25 with your own public IP, and 100.101.102.103 with Home Assistant's address on your tailnet. Your own IP is in the list because the Connect step opens Home Assistant's login page in your browser. That request comes from you, not from Anthropic. If Connect hangs on a page that never loads, your address is missing from the list. Caddy sets the X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host headers by default, and it proxies WebSocket connections. It also gets a TLS (transport layer security) certificate for the hostname itself, as long as the hostname's DNS record points at the VPS.
caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddycaddy validate should finish without an error. From an address outside the list, curl -I https://ha.example.com/ should get no HTTP response at all, because abort closes the connection. Last, add the VPS's tailnet address to Trusted proxies in Home Assistant.
What it does not protect against: every Claude user shares Anthropic's IP ranges. The allowlist keeps out random scanners. Anyone who learns your URL and adds it as their own connector still reaches your login page, so the account password and IP banning still matter. You also now have a VPS to keep patched.
Which path to pick
Nabu Casa is the shortest setup and needs no server of your own. Funnel and Cloudflare Tunnel avoid opening a port at home, but both put the full login page on the open internet. The VPS proxy takes the most work and has the smallest exposure, since only Anthropic's ranges and your own address can open a connection. On every path, the dedicated account and the Read-only switch protect you more than the choice of path does.
Add the connector in Claude
- On claude.ai, open Customize > Connectors and select + Add > Add custom connector. In Claude Desktop, the Home Assistant docs give Settings > Connectors, then Add > Add custom connector.
- Name it
Home Assistantand paste the full URL, for examplehttps://ha.example.com/api/mcp. - Set Authentication to Sign in now and OAuth client to Use Claude's published identity, then select Add.
- On the new connector's page, select Connect and log in to Home Assistant with the dedicated account.
On a Team or Enterprise plan, an Owner adds the connector under Organization settings > Connectors. Each member then finds it under Customize > Connectors and selects Connect, so each member goes through the Home Assistant login.
You choose the published identity because of how Home Assistant handles OAuth. Home Assistant implements OAuth 2.0 with PKCE (proof key for code exchange). It supports OAuth Client ID Metadata Documents, so the client ID and callback URL are set up automatically. Home Assistant does not use a client secret. It also does not support RFC 7591 Dynamic Client Registration, and the docs say clients that strictly require it "cannot register automatically." For other MCP clients, the docs say the Client ID must be the base URL of the client application, "never your Home Assistant instance URL."
Add Home Assistant to Claude Code
claude mcp add --transport http home-assistant https://ha.example.com/api/mcp
claude mcp login home-assistantclaude mcp login runs the server's OAuth flow from your shell. It also accepts --no-browser for SSH sessions on a remote server. By default, claude mcp add uses the local scope, which limits the server to the current project on this machine. Add --scope user to make it available in every project. Inside Claude Code, /mcp shows whether the server is connected. If Claude Code runs on Linux and you have not set it up yet, the install is covered in running Claude on the Linux desktop and in the CLI.
Long-lived tokens or OAuth: which do older guides mean?
Older guides tell you to create a long-lived access token. That was correct when they were written. No single Home Assistant release switched from tokens to OAuth. The change happened in steps:
- The first MCP Server docs, written for 2025.2, said: "For now, we can use Long-lived access token to control access to the API."
- From 31 March 2025, the docs described OAuth through IndieAuth. They also noted that some MCP clients support access tokens but not OAuth.
- PKCE with the S256 method first appears in the Home Assistant source at tag 2026.10.0. It is not in the source at 2026.9.0.
- The current MCP Server page does not mention long-lived tokens.
A guide that pastes a token into a request header describes an older setup. Use the current OAuth steps above instead.
When is the community ha-mcp server the better choice?
ha-mcp is a separate project under the MIT license. The README at its v9.2.0 tag lists 87 tools. The README on its default branch already says 86, so the count changes between builds. Choose ha-mcp when you want a larger, purpose-built tool list than the built-in tool sets offer, and you accept a different credential model.
The recommended install at v9.2.0 is the HA-MCP integration. It runs inside Home Assistant and needs Home Assistant 2026.8.0 or newer. On 2026.8 to 2026.10 you install it through HACS (the Home Assistant Community Store). From 2026.11 it is in Settings > Marketplace. After a restart, add HA-MCP Server under Settings > Devices & services > Add Integration. The integration acts with an administrator's permissions, and its own docs recommend a dedicated HA-MCP account. The project also ships a Docker image, a PyPI package and a Home Assistant app (add-on), and its README describes a local stdio mode for testing only.
Pin the stable release
On 15 November 2026 the latest stable release was v9.2.0, published on 11 November. Development builds (.devN) are published on every push to master, and five dev tags appeared in the 24 hours before this check. The project's own advice is clear: "Dev releases (.devN) may contain bugs. For production use, stick with stable releases." Install the v9.2.0 release, not a .devN build. The Docker image's :latest and :stable tags track stable releases and never dev builds. If you run it with uvx, the README's command ends in @latest. Replace that with @9.2.0, because uv's @ syntax takes an exact version. The PyPI package needs Python 3.13 or 3.14.
The private_ URL is the password
The built-in server makes Claude log in. The main ha-mcp mode does not. On your network its address looks like http://<ha-ip>:9584/private_<random>. Remotely, it is a webhook URL such as https://<your-ha-domain>/api/webhook/<webhook-id>. The project's docs say "the path is the credential", and they tell you to "Treat the URL like a password: don't share it or paste it where it could be logged." Anyone with the full URL reaches your MCP server, and there is no login page in between.
This changes the threat model. A URL pasted into a shared chat or left in a proxy log gives full access. If one leaks, generate a new webhook ID to replace it. Add /readonly to the end of the endpoint to get a connection that hides write tools and blocks write calls. Remote access works through Nabu Casa remote UI or a reverse proxy you already run. For Cloudflare Tunnel, the README points to its Setup Wizard.
ha-mcp also has an OAuth mode, labelled beta. It still asks each user to paste a Home Assistant long-lived access token into a consent form. It is a different mechanism from the built-in server's login.
Why does the connector fail to sign in?
The login page never appears, or Claude says it cannot reach the server. Anthropic's cloud cannot reach the URL. Test it on port 443 from a network outside your home, and check your allowlist if you use one.
Sign-in fails with OAuth errors behind a proxy. The Home Assistant docs name the cause: the reverse-proxy headers (X-Forwarded-Host, X-Forwarded-Proto) are missing or do not match. The docs add that "Conforming OAuth clients reject this metadata." The URL that Home Assistant builds must match the exact hostname and scheme Claude used. Fix the proxy headers and the Trusted proxies setting.
A request to /register returns 404. The client tried Dynamic Client Registration, which Home Assistant does not support. In Claude, set the OAuth client to Use Claude's published identity.
A known open issue. On 15 November 2026, issue #183050 reports a claude.ai connector failing against /api/mcp on Core 2026.11.0. It is open and marked as needing more information, and no fix has been confirmed. Test your connector before you depend on it.
FAQ
Does Claude Desktop connect to Home Assistant from my own computer?
Not for a custom connector. Both Anthropic and Home Assistant say Claude connects from Anthropic's cloud, also in Claude Desktop. That is why Home Assistant needs a public HTTPS address on port 443. The exceptions are local servers in claude_desktop_config.json and Claude Code, which connect from your own machine.
Can Claude open my garage door through Home Assistant MCP?
Yes, if the account and tool set allow it. Assist exposes new covers by default, and covers include garage doors and gates, so the Device control tool set can usually reach them. The Home Assistant tool set can perform any action. If Claude should not move them, remove those entities from Assist exposure or turn on Read-only for the main URL.
Do I still need a long-lived access token for the Home Assistant MCP server?
Not for the built-in server. The current docs use OAuth 2.0 with PKCE and do not mention long-lived tokens. Tokens were the method in the first 2025.2 docs. The community ha-mcp server is different: its beta OAuth mode still asks you to paste a long-lived token.
I am locked out of Home Assistant after the connector failed several times. What happened?
IP banning blocked the address that failed to log in. The Home Assistant docs say the most likely cause is a wrong OAuth detail, such as the client ID or the Home Assistant URL. Open ip_bans.yaml in your Home Assistant configuration directory, remove the entry for the blocked address, and restart Home Assistant. Fix the connector settings before you try again.