MCP-HA-Connect
About
A production-ready Model Context Protocol (MCP) server for Home Assistant integration with AI assistants like Claude.
Details
- Author
- coffeerunhobby
- Categories
- Other, AI
Jump to
Setup
Install MCP-HA-Connect in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/coffeerunhobby/mcp-ha-connect
Follow the installation instructions in the repository README, then restart your MCP client.
A production-ready Model Context Protocol (MCP) server for Home Assistant integration with AI assistants like Claude and LM Studio.
Seedocs/QUICK_START.mdfor Docker, HTTP server mode, n8n integration, and more installation options.
- 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
- 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
- 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-poweredanalyzeSensorsfor 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 AssistantcheckUpdatesphilosophy 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.
- 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
- Log into your Home Assistant instance
- Click on your profile (bottom left)
- Scroll down to "Long-Lived Access Tokens"
- Click "Create Token"
- Give it a name (e.g., "MCP Server")
- Copy the token (shown only once!)
Optional - Chat face (OpenAPI/REST surface)
The server also serves an OpenAPI/REST face (/openapi.json+/api/) for chat UIs like Open WebUI. By default it exposes the classic 8 Home Assistant tools. Tools marked chat-eligible in code can be activated per category with read/write granularity:
Activated chat tools appear in the generated/openapi.jsonasPOST /api/tools/<name>and dispatch through the same handlers, validation, and RBAC as the MCP face.
WhenMCP_AUTH_METHOD=bearer, clients must provide a JWT token in the Authorization header:
Generate tokens with yourMCP_AUTH_SECRETusing HS256 algorithm. The JWT payload should include:
- sub(subject): User identifier for permission lookup
- exp(optional): Expiration timestamp
The server uses role-based access control with binary permission masks:
{ "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"}'
{ "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" } } } }
{ "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" } } } }
For Linux, you may need to addhost.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" ] } } }
Mode 1: MCP Client (Claude Desktop / LM Studio)
Default stdio mode for MCP clients. SeeQuick Startsection for configuration.
For detailed configuration options, seedocs/LOCAL_CLIENT.md.
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
- URL:http://localhost:3000/mcp
- Transport:Streamable HTTP (MCP 2025-03-26)
Seedocs/SSE_API.mdfor complete SSE documentation.
# 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
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
- "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"
The server can be integrated with n8n for automated home monitoring. Pre-built workflows are available in then8n/directory:
- ai-agent-safety-monitor- Critical safety monitoring every 5 minutes
- Open n8n:http://127.0.0.1:5678
- ClickWorkflows→Import from File
- Select JSON file fromn8n-files/
- Activate the workflow
# 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
Use the HTTP transport with your MCP-compatible web client:
- Start server in HTTP mode
- Configure client to usehttp://localhost:3000/mcp
- Set transport to Streamable HTTP (MCP 2025-03-26)
- Enable CORS by adding your origin toMCP_HTTP_ALLOWED_ORIGINS
Connect a stdio-only client (Claude Desktop, LM Studio) to a remote HTTP MCP server usingmcp-remote. On Windows, launch it throughcmd /cand include-yso 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--headervalue.A config like"Authorization: Bearer ${MCP_AUTH_TOKEN}"with a matchingenvblock doesnotwork on Windows:cmd /conly 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 replies401, 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.)
- 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-gatewayto docker args
- 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
- Store.envsecurely (contains access token)
- Nevercommit.envto version control
- Set.envpermissions:chmod 600 .env
- UseHA_STRICT_SSL=truefor HTTPS in production
- Rotate access tokens periodically
- RestrictMCP_HTTP_ALLOWED_ORIGINS(avoid wildcard)
- Bind to127.0.0.1for local-only access
- Enable rate limiting in production (MCP_RATE_LIMIT_ENABLED=true)
⚠️Important:Storing tokens directly in MCP client config files (Claude Desktop, LM Studio) exposes them to anyone with filesystem access. Consider:
- Using.envfiles 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
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 likelistPersons
- Device Control: When to use specialized control tools vs genericcallService
- 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.
Claude Desktop / LM Studio Not Connecting
- Check config file location- Verify you're editing the correct file - Restart the application- Close and reopen after config changes - Check logs- Look for error messages in the application logs - 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/healthreturns200but the client shows"Server disconnected", the auth header is almost certainly malformed. Most common cause: a${VAR}placeholder in the--headervalue that never got expanded (see the warning underWith 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"}}}'
A200with aninitializeresult means the server and token are fine — fix the client config (inline the literal token). A401means the token itself is wrong.
Dockerhost.docker.internalNot Working (Linux)
{ "args": [ "run", "--rm", "-i", "--add-host=host.docker.internal:host-gateway", "-e", "HA_URL=http://host.docker.internal:8123", ... ] }
- Verify URL- Try accessinghttp://your-ha-url:8123/api/in browser
- Check token- Ensure it's a valid long-lived access token
- Network access- Verify MCP server can reach Home Assistant
- SSL issues- TryHA_STRICT_SSL=falsefor testing
- Verify Ollama is running-curl http://your-ollama-url:11434/api/tags
- Check model is available- Ensure model is pulled:ollama pull llama2
- Set AI_PROVIDER- Must be set toollama(notnone)
# 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
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
Coffee Run Hobby (github.com/coffeerunhobby)
- 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
Contributions are welcome! Please feel free to submit a Pull Request.
An MCP server for AI video generation. MCP server for AI video generation. Lets Claude, ChatGPT, OpenClaw , Hermes & other agents create AI videos and publish them to YouTube, TikTok, Instagram etc..
HumanDesign.ai MCP is the official account-connected Human Design server for Claude, ChatGPT, Codex, Cursor, and VS Code.
A Model Context Protocol (MCP) server written in Go that wraps the APsystems OpenAPI, giving AI assistants like Claude direct access to your solar monitoring data. Includes an optional web dashboard for visual monitoring.
MCP server for interacting with the APVISO AI-powered penetration testing platform from Claude Code, Cursor, Windsurf, Codex, and other MCP-compatible tools.
AI-powered text-to-speech MCP server with instant voice cloning. Generate speech from Claude Desktop, Claude Code, or n8n using 5 built-in voices (English, German, French, Spanish) or clone any voice from a short audio sample. Runs fully local, no API keys, no cloud. Supports stdio, SSE, and HTTP transports.
Chess.com player, game, and daily-puzzle tools where each tool ships its own interactive React view — board replays and a playable puzzle widget, not just text. Built with Skybridge for ChatGPT & Claude.
Pre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, and Hermes Agent — fewer tokens, fewer tool calls, 100% local
Live crypto technical analysis MCP server — EMA, RSI, MACD, ATR, Bollinger Bands, TSS scoring, and Claude AI bull/bear debate via CoinGecko free API
A high-performance trading system for Claude Desktop, providing real-time market data via Tiingo and optional Telegram alerts.
Ask Power BI in plain English, from Claude — charts + full ETL context.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.




