MCP-HA-Connect

A production-ready Model Context Protocol (MCP) server for Home Assistant integration with AI assistants like Claude and LM Studio.

See docs/QUICK_START.md for Docker, HTTP server mode, n8n integration, and more installation options.

Key Features

Core Functionality

• Smart Device Control
• Lights: Brightness, color temperature, RGB color, transitions
• Climate: Temperature, HVAC modes, fan modes, humidity
• Covers: Position and tilt control
• Switches: On/off control
• Sensors & Contacts: State monitoring
• Media Players: Playback control, volume, source selection
• Fans: Speed, oscillation, direction
• Locks: Lock/unlock control
• Vacuums: Start, stop, return to base
• Cameras: Motion detection, snapshots

Automation Management

• List all automations with status
• Trigger automations manually with variables
• Enable/disable/toggle automations
• Create new automations via API
• Delete automations
• View automation execution traces
• Reload automations from configuration

System Features

• Direct Home Assistant API integration
• Long-lived access token authentication
• Entity state management
• Service call support
• Advanced entity search
• AI-powered sensor analysis with Ollama
• Multiple transport modes (stdio, Streamable HTTP)
• HTTP server with health checks
• CORS support for browser-based clients
• Structured logging (plain, JSON, GCP-JSON formats)
• Comprehensive configuration validation with Zod
• Full type safety with TypeScript
• Stateful and stateless session support
• JWT authentication with role-based access control
• MCP Server Instructions for improved LLM tool selection

Network Monitoring & Security (TP-Link Omada)

Bring your home network into the same assistant that runs your home. These are the high-value questions an LLM can actually answer about your network:

• Internet & WAN status — "Is my internet up? What's my WAN IP and uplink speed?" Live per-WAN status, plus multi-WAN / ISP health and load-balancing for the gateway.
• Event & alert logs — "What happened on my network?" The site event and alert logs, time-windowed (defaults to the last 7 days), to correlate with Home Assistant history.
• Wireless security — rogue-AP scan results and (on Omada Pro) wireless intrusion detection (WIDS) for genuine network-security awareness.
• Controller & device health — dashboard overview plus top devices by CPU and memory usage, HA-style monitoring of your network stack.
• Speed tests — surface the controller's own speed-test results, pairing with AI-powered analyzeSensors for anomaly detection.
• Pending devices — "Is there a new device waiting to be adopted?"
• Firmware awareness — per-device firmware info and a controller-wide critical-upgrade overview, mirroring the Home Assistant checkUpdates philosophy across the network.
• Client management — list/inspect connected clients, traffic activity, and apply rate-limit profiles, with presence correlation against Home Assistant device trackers.

A discoverable resource-graph mode (MCP_TOOL_REGISTRATION_MODE=graph) exposes all of the above through two tools — omada_browse + omada_read — keeping the tool-schema budget small for low-context models. See the Omada tool tables below for the full eager surface.

Available Tools (60 Total)

Home Assistant Tools (35)

State & Entity Tools

Service & Control Tools

Device Control Tools

Automation Tools

System Tools

Calendar Tools

Omada Network Tools (24)

Site Tools

Device Tools

Client Tools

Rate Limit Tools

Security Tools

Network Configuration Tools

AI Tools (1)

MCP Resources

Getting Your Home Assistant Token

1. Log into your Home Assistant instance
2. Click on your profile (bottom left)
3. Scroll down to "Long-Lived Access Tokens"
4. Click "Create Token"
5. Give it a name (e.g., "MCP Server")
6. Copy the token (shown only once!)

Environment Variables

Required

Optional - Home Assistant

Optional - MCP Server

Optional - HTTP Mode

Optional - SSE Events

Optional - Rate Limiting

Optional - Authentication

JWT Authentication

When MCP_AUTH_METHOD=bearer, clients must provide a JWT token in the Authorization header:

Authorization: Bearer <jwt-token>

Generate tokens with your MCP_AUTH_SECRET using HS256 algorithm. The JWT payload should include:

• sub (subject): User identifier for permission lookup
• exp (optional): Expiration timestamp

Permission System

The server uses role-based access control with binary permission masks:

Predefined Roles:

Configuration Example:

{
  "users": [
    { "sub": "admin@example.com", "role": "admin" },
    { "sub": "user@example.com", "role": "operator" },
    { "sub": "viewer@example.com", "role": "readonly" }
  ],
  "defaultRole": "NONE"
}

Set via environment variable (escape quotes for shell):

MCP_PERMISSIONS_CONFIG='{"users":[{"sub":"admin","role":"admin"}],"defaultRole":"NONE"}'

Optional - AI Provider

Optional - Omada Network Controller

Integration Examples

With Claude Desktop

Once configured, you can ask Claude:

• "Show me all lights in my house"
• "Turn on the kitchen lights to 50% brightness"
• "Set the living room temperature to 72 degrees"
• "Create an automation that turns off all lights at midnight"
• "What automations are currently enabled?"
• "Trigger the morning routine automation"
• "Search for entities with 'bedroom' in their name"
• "Get all climate entities"
• "Analyze my sensors for any issues" (requires Ollama)
• "Check the history of my thermostat"

With n8n Workflows

The server can be integrated with n8n for automated home monitoring. Pre-built workflows are available in the n8n/ directory:

1. ai-agent-safety-monitor - Critical safety monitoring every 5 minutes

Importing Workflows

Method 1: n8n UI

1. Open n8n: http://127.0.0.1:5678
2. Click Workflows → Import from File
3. Select JSON file from n8n-files/
4. Activate the workflow

Method 2: Docker CLI

# Copy workflow to n8n container
docker cp "n8n-files/AI Agent Safety Monitor - Updated.json" n8n:/files/workflow.json

# Import using n8n CLI
docker exec -it n8n n8n import:workflow --input=/files/workflow.json

# Verify import
docker exec -it n8n n8n list:workflow

With Web Applications

Use the HTTP transport with your MCP-compatible web client:

1. Start server in HTTP mode
2. Configure client to use http://localhost:3000/mcp
3. Set transport to Streamable HTTP (MCP 2025-03-26)
4. Enable CORS by adding your origin to MCP_HTTP_ALLOWED_ORIGINS

With Remote MCP Proxy (mcp-remote)

Connect a stdio-only client (Claude Desktop, LM Studio) to a remote HTTP MCP server using mcp-remote. On Windows, launch it through cmd /c and include -y so the first run never blocks on the npx install prompt:

{
  "mcpServers": {
    "homeassistant": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://your-server.example/mcp",
        "--header",
        "Authorization: Bearer <your-jwt-token>"
      ]
    }
  }
}

⚠️ Do not use ${VAR} placeholders in the --header value. A config like "Authorization: Bearer ${MCP_AUTH_TOKEN}" with a matching env block does not work on Windows: cmd /c only expands %VAR% (not ${VAR}), and mcp-remote does not substitute it either. The literal text ${MCP_AUTH_TOKEN} is sent as the token, the server replies 401, and mcp-remote then falls into a failing OAuth flow that surfaces as "Server disconnected". Inline the actual JWT instead. (On macOS/Linux you can instead let your shell expand the variable before the client launches.)

Security Best Practices

Network Security

• Network Segmentation: Run MCP server on private LAN only
• Docker Networks: Use Docker networks for container isolation
• VLAN: Consider VLAN for IoT devices
• No Internet Exposure: Never expose MCP server directly to internet

Token & Configuration Security

• Store .env securely (contains access token)
• Never commit .env to version control
• Set .env permissions: chmod 600 .env
• Use HA_STRICT_SSL=true for HTTPS in production
• Rotate access tokens periodically
• Restrict MCP_HTTP_ALLOWED_ORIGINS (avoid wildcard *)
• Bind to 127.0.0.1 for local-only access
• Enable rate limiting in production (MCP_RATE_LIMIT_ENABLED=true)

MCP Client Configuration Security

⚠️ Important: Storing tokens directly in MCP client config files (Claude Desktop, LM Studio) exposes them to anyone with filesystem access. Consider:

• Using .env files with restricted permissions for Docker/local deployments
• Setting file permissions on config files (e.g., chmod 600)
• Using environment variable substitution if supported by your client
• Never committing config files with real tokens to version control

Server Instructions

The server provides MCP Server Instructions during initialization to help LLMs understand how to optimally use the available tools. Instructions are dynamically generated based on enabled plugins and include:

• Entity Queries: Guidance on pagination, attribute inclusion, and using specialized tools like listPersons
• Device Control: When to use specialized control tools vs generic callService
• Automation Workflows: Best practices for creating and testing automations
• Omada Operations: Site context requirements, client vs device distinction, rate limiting safety
• Cross-Plugin Integration: How HA presence detection correlates with Omada network clients

Instructions follow MCP best practices: concise, actionable, and focused on tool relationships rather than repeating individual tool descriptions.

Development

Setup

# Clone repository
git clone https://github.com/coffeerunhobby/mcp-ha-connect.git
cd mcp-ha-connect

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your Home Assistant details
nano .env

# Build
npm run build

# Run
npm start

Available Scripts

npm run build      # Build TypeScript to dist/
npm run dev        # Run in development mode with watch
npm start          # Run built version
npm test           # Run tests
npm run lint       # Run ESLint
npm run format     # Format code with Prettier

Author

Coffee Run Hobby (github.com/coffeerunhobby)

Links

• GitHub: https://github.com/coffeerunhobby/mcp-ha-connect
• npm: https://www.npmjs.com/package/@coffeerunhobby/mcp-ha-connect
• Docker: https://github.com/coffeerunhobby/mcp-ha-connect/pkgs/container/mcp-ha-connect

Documentation

• Quick Start Guide
• Changelog

Prerequisites

• Node.js 20+ (tested with v20.19.6) - for npm/npx methods
• npm 10.8+ (tested with v10.8.2) - for npm/npx methods
• Docker (optional) - for Docker method
• Home Assistant instance with long-lived access token
• Network access to your Home Assistant instance
• (Optional) Ollama for AI-powered analysis

Advanced Configuration Examples

With AI Analysis (Ollama)

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["-y", "@coffeerunhobby/mcp-ha-connect"],
      "env": {
        "HA_URL": "http://homeassistant.10.0.0.19.nip.io:8123",
        "HA_TOKEN": "your_token",
        "AI_PROVIDER": "ollama",
        "AI_URL": "http://ollama.10.0.0.17.nip.io:11434",
        "AI_MODEL": "llama2"
      }
    }
  }
}

Disable AI Features

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["-y", "@coffeerunhobby/mcp-ha-connect"],
      "env": {
        "HA_URL": "http://homeassistant.10.0.0.19.nip.io:8123",
        "HA_TOKEN": "your_token",
        "AI_PROVIDER": "none"
      }
    }
  }
}

Docker with Network Configuration

For Linux, you may need to add host.docker.internal:

{
  "mcpServers": {
    "homeassistant": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--add-host=host.docker.internal:host-gateway",
        "-e", "HA_URL=http://host.docker.internal:8123",
        "-e", "HA_TOKEN=your_token",
        "ghcr.io/coffeerunhobby/mcp-ha-connect:latest"
      ]
    }
  }
}

Usage Modes

Mode 1: MCP Client (Claude Desktop / LM Studio)

Default stdio mode for MCP clients. See Quick Start section for configuration.

For detailed configuration options, see docs/LOCAL_CLIENT.md.

Mode 2: HTTP Server

Start as standalone HTTP server for web applications:

# Using npx
npx @coffeerunhobby/mcp-ha-connect

# Or with environment variables
MCP_SERVER_USE_HTTP=true \
MCP_HTTP_PORT=3000 \
HA_URL=http://homeassistant.10.0.0.19.nip.io:8123 \
HA_TOKEN=your_token \
npx @coffeerunhobby/mcp-ha-connect

Streamable HTTP Transport

Configure your MCP client to use:

• URL: http://localhost:3000/mcp
• Transport: Streamable HTTP (MCP 2025-03-26)

SSE Event Subscription

Subscribe to real-time events:

const eventSource = new EventSource(
  'http://localhost:3000/subscribe_events?domain=light&entity_id=light.living_room'
);

eventSource.addEventListener('state_changed', (event) => {
  const data = JSON.parse(event.data);
  console.log('Entity changed:', data.entity_id, data.new_state);
});

See docs/SSE_API.md for complete SSE documentation.

Mode 3: Docker Standalone

# Pull image
docker pull ghcr.io/coffeerunhobby/mcp-ha-connect:latest

# Run in HTTP mode
docker run -d --name mcp-ha-connect \
  -e HA_URL=http://homeassistant.10.0.0.19.nip.io:8123 \
  -e HA_TOKEN=your_token \
  -e MCP_SERVER_USE_HTTP=true \
  -p 3000:3000 \
  ghcr.io/coffeerunhobby/mcp-ha-connect:latest

Mode 4: Docker Compose

version: '3.8'

services:
  mcp-ha-connect:
    image: ghcr.io/coffeerunhobby/mcp-ha-connect:latest
    container_name: mcp-ha-connect
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - HA_URL=http://homeassistant.10.0.0.19.nip.io:8123
      - HA_TOKEN=${HA_TOKEN}
      - MCP_SERVER_USE_HTTP=true
      - MCP_HTTP_BIND_ADDR=0.0.0.0
    networks:
      - home-automation

networks:
  home-automation:
    driver: bridge

Network Configuration Notes

• host.docker.internal - Use this to access services on your host machine from Docker
  • Works on Windows and macOS by default
  • On Linux, add --add-host=host.docker.internal:host-gateway to docker args
• Direct IP - Use your machine's IP address (e.g., http://10.0.0.19:8123)
• nip.io domains - Use wildcard DNS for easy local development (e.g., http://homeassistant.10.0.0.19.nip.io:8123)

Troubleshooting

Claude Desktop / LM Studio Not Connecting

1. Check config file location - Verify you're editing the correct file
2. Restart the application - Close and reopen after config changes
3. Check logs - Look for error messages in the application logs
4. Test connection manually:

# Test npx
npx @coffeerunhobby/mcp-ha-connect

# Test Docker
docker run --rm -i \
  -e HA_URL=http://homeassistant.10.0.0.19.nip.io:8123 \
  -e HA_TOKEN=your_token \
  ghcr.io/coffeerunhobby/mcp-ha-connect:latest

mcp-remote Shows "Server disconnected" (401)

If /health returns 200 but the client shows "Server disconnected", the auth header is almost certainly malformed. Most common cause: a ${VAR} placeholder in the --header value that never got expanded (see the warning under With Remote MCP Proxy). Verify the endpoint accepts your token directly:

curl -i -X POST https://your-server.example/mcp \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"diag","version":"1.0"}}}'

A 200 with an initialize result means the server and token are fine — fix the client config (inline the literal token). A 401 means the token itself is wrong.

Docker host.docker.internal Not Working (Linux)

Add host gateway:

{
  "args": [
    "run",
    "--rm",
    "-i",
    "--add-host=host.docker.internal:host-gateway",
    "-e", "HA_URL=http://host.docker.internal:8123",
    ...
  ]
}

Home Assistant Connection Issues

1. Verify URL - Try accessing http://your-ha-url:8123/api/ in browser
2. Check token - Ensure it's a valid long-lived access token
3. Network access - Verify MCP server can reach Home Assistant
4. SSL issues - Try HA_STRICT_SSL=false for testing

AI Analysis Not Working

1. Verify Ollama is running - curl http://your-ollama-url:11434/api/tags
2. Check model is available - Ensure model is pulled: ollama pull llama2
3. Set AI_PROVIDER - Must be set to ollama (not none)

License

MIT