Home Assistant and Claude Code: Setup, Usage and Control From Your Phone

Home Assistant runs the house. Claude Code runs in a terminal and can read files, run commands and talk to other services over MCP. Connect the two and you can ask Claude to check the state of every exposed device, write automations, dig through logs and fix a broken YAML block, from the same window you use for everything else.

This guide covers the built-in Home Assistant MCP Server integration, connecting Claude Code to it, day-to-day use, and Remote Control so you can drive the session from your phone.

What you need

• Home AssistantVersion 2025.2 or later. The MCP Server integration ships with core, so there is nothing to install from HACS.
• Claude CodeInstalled on a Mac, Linux box or Windows with WSL, signed in with a claude.ai account. Remote Control needs a Pro, Max, Team or Enterprise plan; an API key alone will not do.
• A reachable URLOn the same network, http://homeassistant.local:8123 works. From anywhere else you need Nabu Casa, a reverse proxy or a VPN. Remote Control does not change this: the Claude Code process still has to reach Home Assistant itself.

Step 1: turn on the MCP Server in Home Assistant

1. Open Settings > Devices & services.
2. Select Add Integration and search for Model Context Protocol Server.
3. Leave Control Home Assistant enabled if you want Claude to change device state as well as read it.

The server sits at /api/mcp and uses the same Assist API your voice assistant uses. It only sees entities you have exposed. Go to Settings > Voice assistants > Expose and check the list before you connect anything. If a device is not exposed, Claude cannot see it, let alone control it.

Step 2: connect Claude Code

Claude Code speaks the remote MCP protocol directly, so no proxy is needed. In your shell:

claude mcp add-json "HA" '{
  "type": "http",
  "url": "https://your-home-assistant-url/api/mcp",
  "oauth": {
    "clientId": "http://localhost:12345",
    "callbackPort": 12345
  }
}' --client-secret

Then:

1. Run claude.
2. Type /mcp, pick HA and choose Authenticate.
3. A browser tab opens on your Home Assistant login. Sign in and approve the connection.

Back in the terminal, /mcp should show HA as connected. If the browser step fails repeatedly, check the URL and port, then look in ip_bans.yaml in your config directory. Home Assistant bans IPs after enough failed logins, and a few typos during setup can trip it.

If you would rather not use OAuth, create a long-lived access token under Profile > Security and run a local mcp-proxy instead. The Home Assistant docs cover that route for Cursor and Claude Desktop, and the same config works in Claude Code.

Step 3: use it

Claude will ask permission before each tool call the first time. Say yes, or use /permissions to allow the Home Assistant tools for the session.

Some prompts that earn their keep:

For file editing, run Claude Code from a directory that contains your Home Assistant config. On Home Assistant OS, the Samba add-on or an SSHFS mount gets the config folder onto your machine. Claude then has the MCP server for live state and the filesystem for configuration, which is the combination that makes it useful.

Remote Control: run it from your phone

Claude Code’s Remote Control links a session on your machine to the Claude mobile app or claude.ai/code. The session keeps running locally, with your MCP connection and files. Your phone is a window into it.

Start it from your Home Assistant config directory:

claude remote-control --name "Home Assistant"

Press the spacebar to show a QR code. Scan it with the Claude app on iOS or Android and the session opens. Or open Code in the app and pick it from the list.

If you are already in a session, /rc does the same thing without restarting.

From the phone you can send prompts, approve tool calls, attach a photo of a wiring diagram, and stop a task that is going sideways. Permission prompts queue while you are away and turn up as push notifications if you enable Push when actions required under /config.

Security notes

Expose only the entities you want an AI to touch. Locks, garage doors and alarm panels are a judgement call; you can leave them out of the exposed list and still get value from everything else.

Use OAuth over long-lived tokens where you can. A token in a config file is a token that can leak. If you must use one, put it in an environment variable, not the JSON.

Keep Home Assistant patched. The MCP endpoint is an authenticated API surface on your instance, and it inherits every vulnerability in the auth layer.