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.

OAuth stopped working after upgrading to v7.0.0

v7.0.0 removed the Home Assistant URL field from the OAuth consent form to fix security vulnerabilities (SSRF and XSS). Set HOMEASSISTANT_URL as a server-side environment variable before starting ha-mcp.

# Docker
docker run -d -p 8086:8086 \
  -e HOMEASSISTANT_URL=https://your-ha-instance.example.com \
  -e MCP_BASE_URL=https://your-mcp-server.example.com \
  ghcr.io/homeassistant-ai/ha-mcp:latest ha-mcp-oauth

# uvx
HOMEASSISTANT_URL=https://your-ha-instance.example.com \
MCP_BASE_URL=https://your-mcp-server.example.com \
uvx --from=ha-mcp@latest ha-mcp-oauth

The consent form now accepts only the token. See the full migration guide for details.

macOS: "All connection attempts failed" to local Home Assistant

If ha-mcp connects to the demo server but fails to reach your local Home Assistant (192.168.x.x, 10.x.x.x, etc.) on macOS, check the following. See #867 (Local Network Privacy), #630 (env vars), #773 (Python version) for related reports.

1. macOS Local Network Privacy (Sequoia 15+)

macOS Sequoia silently blocks subprocess connections to local network IPs. Claude Desktop spawns uvx as a child process, and macOS may block its outbound LAN connections without showing a permission dialog.

• Check System Settings → Privacy & Security → Local Network for Claude Desktop
• If Claude Desktop is not listed, try restarting it to trigger the permission prompt

Workaround — SSH tunnel to localhost:

macOS does not restrict connections to localhost, so an SSH port forward bypasses the restriction:

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

Then set HOMEASSISTANT_URL to http://localhost:8123 in your config.

2. Firewall software (Little Snitch, Lulu, etc.)

Third-party firewalls may block python or node processes spawned by Claude Desktop. Check your firewall rules and allow connections for these processes. See #780 for an example resolution.

3. http:// vs https://

Home Assistant running in container mode (Docker, K3s) uses HTTP by default. Using https:// causes a TLS handshake error. Use http:// unless you have explicitly configured SSL/TLS or a reverse proxy.

4. Python version too old

ha-mcp requires Python 3.13+. If you are on Python 3.12 or older, uvx installs an outdated version with known bugs (including read-only filesystem errors). Upgrade Python:

brew install python@3.13

Then force a refresh:

uvx --refresh ha-mcp@latest

If uvx still uses the old Python after installing 3.13, explicitly pin it by adding --python 3.13 to your config args:

"args": ["--python", "3.13", "ha-mcp@latest"]

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 (traditional installer): %APPDATA%\Claude\claude_desktop_config.json
   • Windows (Microsoft Store): path varies by package — see the Windows setup guide for a detection snippet
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?"

Can't connect remotely? Try the Webhook Proxy add-on

If you're having trouble setting up remote access — TLS errors, Cloudflare configuration issues, or port forwarding problems — the Webhook Proxy add-on may be a simpler alternative.

Instead of requiring a dedicated tunnel to port 9583, the Webhook Proxy routes MCP traffic through Home Assistant's main port (8123) via a webhook. If you already have Nabu Casa or any reverse proxy pointing at your HA instance, this can be the easiest remote setup.

1. Install the MCP Server add-on and the Webhook Proxy add-on from the add-on store
2. Start the webhook proxy and restart Home Assistant when prompted
3. Copy the webhook URL from the add-on logs
4. Use that URL in your MCP client configuration

See #784 for an example where this resolved a TLS connection issue.

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

Antigravity client troubleshooting

• "Unexpected server output" error: Add FASTMCP_SHOW_SERVER_BANNER=false to your stdio env config. This disables the startup banner that Antigravity misinterprets as unexpected output.
• "EOF" errors: Use absolute paths for the command, not relative paths.
• First run timeout: Run uvx ha-mcp@latest --version in your terminal first to download and cache the package before Antigravity tries to start it.
• Tools load but fail when called: Try switching to stdio mode instead of HTTP. HTTP mode can experience "connection closed" or reconnection errors with this client.
• Connection issues after config changes: Restart the Agent session in Antigravity after saving any config changes.

Claude.ai connection issues

If tools stop responding or the connector appears disconnected in Claude.ai:

1. Restart both Claude.ai and the MCP server. Refresh the Claude.ai page in your browser and restart the ha-mcp process (or Docker container). Either side can hold stale connection state.
2. Check that your tunnel (Cloudflare, ngrok, etc.) is still running and the URL has not changed.
3. Verify the server is reachable by visiting the MCP URL directly in your browser — you should see a response from the server.

Test ha-mcp without configuring a client

Before setting up a client, you can run a quick smoke test against the public demo server to confirm uvx is installed and ha-mcp launches correctly:

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

This starts ha-mcp in stdio mode connected to the public demo Home Assistant instance. Press Ctrl+C to stop. If it launches without errors, your environment is ready — replace the URL and token with your own values to connect to your Home Assistant.

Keep ha-mcp-web running in the background

To run the ha-mcp HTTP server detached from the terminal so it survives logout:

nohup uvx --from ha-mcp@latest ha-mcp-web > /dev/null 2>&1 &

nohup detaches the process from the terminal and redirects output to /dev/null. The trailing & sends it to the background. For more robust setups (auto-restart on crash, start on boot), use systemd or the Home Assistant add-on instead.

Docker: changing the port requires updating both places

When running ha-mcp-web in Docker, the port is set in two independent places and they must match:

• The second number in -p HOST:CONTAINER — this is the container-side port Docker listens on
• The MCP_PORT environment variable — this is the port ha-mcp binds inside the container

If these differ, the container starts but requests never reach the server. Example using port 9000:

docker run -d --name ha-mcp \
  -p 9000:9000 \
  -e HOMEASSISTANT_URL=http://homeassistant.local:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  -e MCP_PORT=9000 \
  ghcr.io/homeassistant-ai/ha-mcp:latest \
  ha-mcp-web

The first number in -p (the host port) can be anything — only the second number must match MCP_PORT.

What is the custom component and why do I need it?

Some tools require a companion custom component installed in Home Assistant. Standard HA APIs do not expose file system access or YAML config editing. This component provides both.

Tools that require the component:

• ha_config_set_yaml — Safely add, replace, or remove top-level YAML keys in configuration.yaml and package files (automatic backup, validation, and config check)
• ha_list_files — List files in allowed directories (www/, themes/, custom_templates/)
• ha_read_file — Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/)
• ha_write_file — Write files to allowed directories
• ha_delete_file — Delete files from allowed directories

All other tools work without the component. These five return an error with installation instructions if the component is missing.

How do I install it?

Using HACS (recommended):

To add manually: open HACS > Integrations > three-dot menu > Custom repositories > add https://github.com/homeassistant-ai/ha-mcp (category: Integration) > Download.

After installing, restart Home Assistant. Then open Settings > Devices & Services > Add Integration and search for HA MCP Tools.

Manual install: Copy custom_components/ha_mcp_tools/ from the repository into your HA config's custom_components/ directory. Restart Home Assistant, then add the integration as described above.

Do I also need to enable feature flags?

Yes. The component is required, but the tools are also gated by feature flags for safety: