macOS Setup Guide - Home Assistant MCP

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.

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