macOS Setup Guide

Claude Desktop + Home Assistant in ~10 minutes

Works with free Claude account - no subscription needed.

This is the local (stdio) setup. ha-mcp runs on this computer and talks to Claude Desktop directly. You do not need the Home Assistant App (add-on) for this, and this config does not use it — don't set up both. Running Home Assistant OS and prefer to run ha-mcp inside HA with no access token to manage? Use the App (add-on) guide instead.

Create a Claude Account

Go to claude.ai and create a free account.

Run the Installer

Open Terminal and paste:

curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh

This installs the required tools and configures Claude Desktop for the demo environment.

Manual Installation (if the installer doesn't work)

Install uv

brew install uv

Or without Homebrew: curl -LsSf https://astral.sh/uv/install.sh | sh

Configure Claude Desktop

1. Open Claude Desktop
2. Menu bar → Claude → Settings... → Developer → Edit Config
3. Paste the following configuration:

{
  "mcpServers": {
    "Home Assistant": {
      "command": "uvx",
      "args": ["ha-mcp@latest"],
      "env": {
        "HOMEASSISTANT_URL": "https://ha-mcp-demo-server.qc-h.net",
        "HOMEASSISTANT_TOKEN": "demo"
      }
    }
  }
}

4. Save and restart Claude: Claude menu → Quit Claude, then reopen.

✓

Optional: Quick Test

Before setting up Claude Desktop, you can smoke-test that uvx and ha-mcp work from a bare terminal using the public demo server:

HOMEASSISTANT_URL=https://ha-mcp-demo-server.qc-h.net HOMEASSISTANT_TOKEN=demo uvx ha-mcp@latest

If it starts without errors and waits for input, everything is working. Press Ctrl+C to exit and continue with the steps below.

Install or Restart Claude Desktop

Download and install Claude Desktop from claude.ai/download.

Already have it? Restart it: Claude menu → Quit Claude, then reopen.

Test It

Open Claude Desktop and ask:

Can you see my Home Assistant?

Claude should respond with a list of entities from the demo environment (lights, sensors, switches, etc.).

Explore the Demo

The demo environment is a real Home Assistant you can experiment with:

Web UI: ha-mcp-demo-server.qc-h.net

Login: mcp / mcp

Note: Resets weekly - your changes won't persist

Try asking Claude:

"Turn on the kitchen lights"
"What's the temperature in the living room?"
"Create an automation that turns off all lights at midnight"

Connect Your Home Assistant

Ready to use your own Home Assistant? Edit the config file:

open "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Replace the demo values:

{
  "mcpServers": {
    "Home Assistant": {
      "command": "uvx",
      "args": ["ha-mcp@latest"],
      "env": {
        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
        "HOMEASSISTANT_TOKEN": "your_long_lived_token"
      }
    }
  }
}

To get your token:

1. Open Home Assistant in your browser
2. Click your username (bottom left)
3. Security tab → Long-lived access tokens
4. Create token → Copy immediately (shown only once)

Then restart Claude: Claude menu → Quit Claude, then reopen.

Troubleshooting: Can't Connect to Local HA?

If the demo server works but your local Home Assistant doesn't, check the following:

1. macOS Local Network Privacy (Sequoia 15+)

macOS may silently block Claude Desktop subprocesses from accessing local network IPs (192.168.x.x, 10.x.x.x). Check System Settings → Privacy & Security → Local Network for Claude Desktop.

Workaround — SSH tunnel to localhost:

ssh -N -L 8123:localhost:8123 user@your-ha-server-ip

Then set HOMEASSISTANT_URL to http://localhost:8123.

2. Firewall software

Little Snitch, Lulu, or similar tools may block python/node connections from Claude Desktop. Add firewall rules to allow them. See #780.

3. http:// vs https://

HA in container mode (Docker, K3s) uses HTTP by default. Use http:// unless you configured SSL/TLS or a reverse proxy.

4. Python 3.13 required

ha-mcp requires Python 3.13+. Older versions get outdated ha-mcp with known bugs.

brew install python@3.13
uvx --refresh ha-mcp@latest

If uvx still picks the old Python, add "--python", "3.13" to your config args.

See the FAQ for full details.

💡

Tip: The ha-mcp Settings Page

ha-mcp ships a local 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 (handy if you find Claude reaching for tools you'd rather it didn't, or want to surface a niche tool you use often).

The easiest way to find the URL: ask Claude something like "how do I open the ha-mcp settings page?" — the URL is included in ha_get_overview's response. You can also read it directly from ~/.ha-mcp/ui.url.

The page is bound to 127.0.0.1 only and gated by a random secret path. See the FAQ for every way to reach it (Docker, app, remote) and how to disable the settings server if you don't want it.

Share Your Feedback

We'd love to hear how you're using ha-mcp!

GitHub Discussions — Share your automations, ask questions
GitHub Issues — Report bugs or request features

Having issues? See the FAQ & Troubleshooting Guide