Windows 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 Windows PowerShell (from Start menu) and paste:

irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex

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

Manual Installation (if the installer doesn't work)

Install uv

Open PowerShell or cmd:

winget install --id=astral-sh.uv -e

Configure Claude Desktop

1. Open Claude Desktop
2. 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: File → Exit, then reopen.

Behind antivirus or a corporate proxy? If uvx fails with invalid peer certificate: UnknownIssuer when downloading ha-mcp, your security software's HTTPS scanning is breaking the PyPI download. Open your Claude Desktop config (Settings → Developer → Edit Config, or see Step 6) and add "UV_NATIVE_TLS": "1" to the server's env block — see the FAQ.

Install or Restart Claude Desktop

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

Already have it? Restart it: File → Exit, 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:

If you installed Claude Desktop from the Microsoft Store, run this in PowerShell to find your config path:

$pkg = Get-AppxPackage -Name Claude -ErrorAction SilentlyContinue | Select-Object -First 1; if ($pkg) { "$env:LOCALAPPDATA\Packages\$($pkg.PackageFamilyName)\LocalCache\Roaming\Claude\claude_desktop_config.json" } else { "$env:APPDATA\Claude\claude_desktop_config.json" }

Or open it directly (works for the traditional installer):

notepad "$env:APPDATA\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: File → Exit, then reopen.

💡

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 %USERPROFILE%\.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