macOS: ConnectError when connecting to local HA instance via Claude Desktop (Local Network permission + http vs https)

[OscarAlmgren]

Environment

• Home Assistant: Running in container mode (Docker/K3s) on a local server (wardrobe/home server, same LAN)
• HA MCP server: ha-mcp via uvx ha-mcp@latest configured in claude_desktop_config.json
• Client: macOS (Sequoia 15), Claude Desktop
• Network: HA server and Mac on the same local network (e.g. 192.168.0.x)

Problem

After correctly configuring claude_desktop_config.json with a valid HOMEASSISTANT_URL and HOMEASSISTANT_TOKEN, every tool call fails with:

ConnectError: All connection attempts failed
HomeAssistantConnectionError: Failed to connect to Home Assistant: All connection attempts failed

The MCP server starts successfully, tools are listed, but any actual tool call (e.g. ha_get_overview) fails immediately.

Root Causes Found

1. macOS Local Network permission blocks subprocess connections

Claude Desktop spawns uvx as a child process. macOS silently blocks outbound TCP connections to local network IPs (192.168.x.x, 10.x.x.x, etc.) for subprocesses spawned by apps that haven't been granted Local Network permission.

Crucially, no permission dialog is shown for CLI subprocesses — the connection just fails. Claude Desktop itself does not appear in System Settings → Privacy & Security → Local Network, so there is no way to grant the permission manually.

This means HOMEASSISTANT_URL=http://192.168.0.x:8123 will always fail when ha-mcp is invoked from Claude Desktop on macOS, regardless of whether the URL and token are correct.

Verification: The same Python environment (uvx's cached Python) can reach the HA API fine when run directly from Terminal — but not when spawned by Claude Desktop.

2. https:// vs http:// — HA container mode uses HTTP by default

HA running in container mode (not HAOS or Supervised) does not configure SSL/TLS by default. Using https:// in HOMEASSISTANT_URL causes a TLS handshake error:

error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version

Use http:// unless you have explicitly configured a reverse proxy with TLS.

Workaround: SSH tunnel to localhost

Since macOS does not restrict connections to localhost, an SSH port forward bypasses the Local Network permission block entirely.

One-time test:

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

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

Persistent (macOS LaunchAgent) — survives reboots and auto-reconnects:

Create ~/Library/LaunchAgents/com.user.ha-tunnel.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.ha-tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/ssh</string>
        <string>-N</string>
        <string>-o</string><string>StrictHostKeyChecking=no</string>
        <string>-o</string><string>ExitOnForwardFailure=yes</string>
        <string>-o</string><string>ServerAliveInterval=30</string>
        <string>-o</string><string>ServerAliveCountMax=3</string>
        <string>-L</string><string>8123:localhost:8123</string>
        <string>user@192.168.0.x</string>
    </array>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><true/>
</dict>
</plist>

Load it:

launchctl load ~/Library/LaunchAgents/com.user.ha-tunnel.plist

Update claude_desktop_config.json:

{
  "mcpServers": {
    "Home Assistant": {
      "command": "uvx",
      "args": ["ha-mcp@latest"],
      "env": {
        "HOMEASSISTANT_URL": "http://localhost:8123",
        "HOMEASSISTANT_TOKEN": "your-token-here"
      }
    }
  }
}

Suggested Doc Addition

A macOS troubleshooting section covering:

• Use http:// not https:// for container-mode HA without a TLS reverse proxy
• If on the same LAN as your HA server, use an SSH tunnel to localhost to bypass macOS Local Network permission restrictions on Claude Desktop subprocesses
• Symptom to look for: ConnectError: All connection attempts failed despite correct URL and token (confirmed working from Terminal)

[github-actions]

🔍 Analysis

The issue describes a common connection failure on macOS Sequoia (15) when using Claude Desktop to connect to a local Home Assistant instance. This is primarily caused by macOS Local Network permissions, which silently block subprocesses (like uvx spawned by Claude Desktop) from accessing the local network (e.g., 192.168.x.x).

Additionally, many users encounter connection errors because they use https:// by default, whereas Home Assistant running in container mode (Docker/K3s) defaults to http:// unless a reverse proxy or SSL is explicitly configured.

Since macOS does not restrict connections to localhost, the most reliable workaround is creating an SSH tunnel from the Mac to the Home Assistant server.

🛠️ Suggested Steps

1. Check your protocol: Ensure you are using http:// instead of https:// if your Home Assistant instance does not have SSL/TLS configured (standard for Docker installations).
2. Test with an SSH Tunnel: If the connection still fails despite correct credentials, run this command in your Mac terminal:
   ssh -N -L 8123:localhost:8123 user@your-ha-server-ip
   Then set HOMEASSISTANT_URL to http://localhost:8123 in your config.
3. Use a persistent tunnel: For a permanent fix, create a macOS LaunchAgent to keep the SSH tunnel running automatically in the background.

📊 Technical Analysis (for maintainers)

Root Cause

• macOS Local Network Isolation: Claude Desktop (the parent app) may not have triggered the "Local Network" permission prompt, or its child processes (like uvx) are being denied access to local LAN IPs by the OS sandbox.
• Protocol Mismatch: HA container mode uses HTTP. Attempting to connect via HTTPS causes a TLS handshake error (tlsv1 alert protocol version).

Affected Code

• src/ha_mcp/client/rest_client.py:113 - HomeAssistantConnectionError should provide more specific hints for macOS users when a connection fails.
• docs/FAQ.md - Needs a section dedicated to macOS local connection issues.
• docs/macOS-uv-guide.md - Should include the SSH tunnel workaround as it's a common requirement for local setups.

Proposed Fix

--- a/src/ha_mcp/client/rest_client.py
+++ b/src/ha_mcp/client/rest_client.py
@@ -10,6 +10,7 @@
 import asyncio
 import json
 import logging
+import sys
 from typing import Any
 
 import httpx
@@ -113,9 +114,19 @@
                 return {}
 
         except httpx.ConnectError as e:
-            raise HomeAssistantConnectionError(
-                f"Failed to connect to Home Assistant: {e}"
-            ) from e
+            msg = f"Failed to connect to Home Assistant: {e}"
+            if sys.platform == "darwin":
+                msg += (
+                    "\n\nTROUBLESHOOTING (macOS):"
+                    "\n1. macOS may block local network access for Claude Desktop subprocesses."
+                    "\n2. Ensure you're using http:// unless you have configured SSL/TLS."
+                    "\n3. Use an SSH tunnel to localhost:8123 as a workaround."
+                    "\nSee: https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/FAQ.md"
+                )
+            raise HomeAssistantConnectionError(msg) from e
         except httpx.TimeoutException as e:
             raise HomeAssistantConnectionError(f"Request timeout: {e}") from e
         except httpx.HTTPError as e:

Related Issues/PRs

• macOS: ConnectError when connecting to local HA instance via Claude Desktop (Local Network permission + http vs https) #867 - macOS: ConnectError when connecting to local HA instance
• [BUG] Couldn't reach MCP server #783 - Connection issues with Cloudflare "Block AI bots"

---

🤖 Automated analysis by Issue Bot

[kingpanther13]

Thank you for doing the research on this! I don't think any of the maintainers here have a Mac so it has been hard to troubleshoot the Mac issues that pop up. I just made a PR that should address all of this, and the other Mac issue which I believe was related.

[OscarAlmgren]

Mate, this was (almost) all Claude Code. 😄 Error triangulation, root cause analysis, the suggested fix, the GH issue registration. We live in the future.

[kingpanther13]

Right, but you're the first person with a mac to do it this way lol. If I tried that on my windows or Android devices it would just hallucinate something.

[github-actions]

✅ This issue has been addressed in the dev channel!

A fix for this issue has been merged to master (PR #897) and is available for testing in the dev channel.

Test the fix before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

After testing:

• ✅ If it's fixed: Great! Feel free to comment here to confirm
• ❌ If still broken: Open a new issue and reference macOS: ConnectError when connecting to local HA instance via Claude Desktop (Local Network permission + http vs https) #867
  • Closed issues can't be reopened by reporters
  • A new issue helps us track the problem properly