FAQ & Troubleshooting

Do I need a Claude Pro subscription?

No. Claude Desktop works with a free Claude account. The MCP integration is available to all users, though free accounts have usage limits.

You can also use ha-mcp with other AI clients. See the Setup Wizard for 15+ supported clients.

Do I need the Home Assistant Add-on?

No. The HA add-on is just one installation method. Most users run ha-mcp directly on their computer using uvx (recommended for Claude Desktop). The add-on is only needed if you want to run ha-mcp inside your Home Assistant OS environment.

What's the difference between ha-mcp and Home Assistant's built-in MCP?

Built-in = operate devices. ha-mcp = administer your system.

SSL certificate errors (self-signed certificates)

If your Home Assistant uses HTTPS with a self-signed certificate or custom CA, you may see SSL verification errors.

Docker solution:

1. Create a combined CA bundle:

   cat $(python3 -m certifi) /path/to/your-ca.crt > combined-ca-bundle.crt

2. Mount it and set SSL_CERT_FILE:

   docker run --rm \
     -e SSL_CERT_FILE=/certs/ca-bundle.crt \
     -v ./combined-ca-bundle.crt:/certs/ca-bundle.crt:ro \
     ...

"uvx not found" error

After installing uv, restart your terminal (or Claude Desktop) for the PATH changes to take effect.

# Reload shell or restart terminal
source ~/.zshrc
# Or verify with full path
~/.local/bin/uvx --version

# Restart PowerShell/cmd after installing uv
# Or use full path
%USERPROFILE%\.local\bin\uvx.exe --version

MCP server not showing in Claude Desktop

1. Restart Claude completely - Use Cmd+Q (Mac) or Alt+F4 (Windows), not just close the window
2. Check config file location:
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Verify JSON syntax - No trailing commas, proper quotes
4. Check the MCP icon - Bottom left of Claude Desktop shows connected servers

"Token invalid" or authentication errors

1. Generate a new token:
   • Home Assistant → Click your username (bottom left)
   • Security tab → Long-lived access tokens
   • Create Token → Copy immediately (shown only once)
2. Check token format - Don't wrap the token in quotes in your config
3. Token expiration - Tokens don't expire by default, but can be revoked

Claude says it can't see Home Assistant

1. Open Claude Desktop Settings (gear icon)
2. Go to the Developer tab
3. Check Local MCP Servers for any errors
4. If "Home Assistant" is not listed, check your config file syntax
5. Try asking Claude: "Can you list your available tools?"

Server works but responses are slow

1. First request is slow - uvx downloads packages on first run
2. Subsequent requests - Should be faster (packages cached)
3. Alternative - Use Docker for consistent performance