MCP-HA-Connect
A production-ready Model Context Protocol (MCP) server for Home Assistant integration with AI assistants like Claude and LM Studio, with network management for TP-Link Omada and Ruijie / Reyee routers through one vendor-neutral set of net_ tools.
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
analyzeSensorsfor 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
checkUpdatesphilosophy across the network. - Client management — list/inspect connected clients, traffic activity, and apply rate-limit profiles, with presence correlation against Home Assistant device trackers.
Vendor-neutral network management (net_ tools)
- One model for every vendor — networks (VLANs, DHCP), Wi-Fi, rules between networks, clients and the network each is on, switch ports, the mDNS repeater and firmware, the same way on TP-Link Omada and Ruijie / Reyee routers.
- Safe changes — every change has a dry run; anything that would cut devices off needs the dry run's
basisandallowLockout, and is refused if the network changed in between. The controller's and this server's own connections are protected. - Firmware — what each device runs and is offered; on Ruijie, the upgrade itself (ADMIN only).
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 (112 Total)
With every plugin on in the default eager mode: Home Assistant 38 (including the 3 owner-question tools, when
MCP_OWNER_QUESTIONS_ENABLED is on), Omada 49, net_ 23, AI 1 and invokeAction 1 (only with MCP_REST_ACTIONS).
In graph mode the Omada reads collapse into omada_browse + omada_read (Omada 26, 89 in total).
Home Assistant Tools (38)
State & Entity Tools
Service & Control Tools
Device Control Tools
Owner Questions (approval on the phone)
Ask the owner a question as a phone notification with up to 3 buttons and read back the tap. HTTP mode only; needs an admin Home Assistant token (button taps are admin-only events) and MCP_AUTH_SECRET so open questions survive a restart. Everything except an explicit approving answer counts as NO.
Taps are verified with signed button ids and must come from the mobile app (an automation cannot fake one); set MCP_OWNER_QUESTIONS_HA_USERS so only your HA user can answer. Only the client that asked can read the answer; at most 3 open questions and 30 per hour per client.
Known limit: cancellations and answers are kept in memory. After a restart, someone with a Home Assistant login could re-send an old button id through HA's own API and answer a question that had been cancelled or denied (the phone no longer shows its buttons). That access already allows controlling the house directly.
Automation Tools
System Tools
Calendar Tools
Omada Network Tools (49)
Site Tools
Device Tools
Client Tools
Rate Limit Tools
Client and Device Actions
Client Diagnosis and MAC Groups
Access Control (schedules, groups, gateway ACLs)
Lets the controller enforce a schedule itself (e.g. a curfew) instead of a daily block/unblock loop. All writes need CONFIGURE.
Security Tools
Network Configuration Tools
Vendor-neutral Network Tools (23)
The net_ tools describe networks the same way for every controller vendor: one shared model, with an adapter per
vendor (TP-Link Omada, and Ruijie / Reyee routers read-only since 2.5.0; UniFi and MikroTik are planned). Each adapter
says per feature whether it is native, built from several objects, or unsupported (net_capabilities), and refuses what
it can't do instead of dropping it. With several controllers configured, every net_ tool takes an optional
controller (omada or ruijie); without it Omada answers.
Every change is planned first: dryRun shows the steps, what they mean, which online devices would be cut off, and a
basis (a fingerprint of the change and what it read). Passing that basis when applying refuses the change if it
is another change, or the controller or those devices changed since; allowLockout (cutting devices off) requires it.
Wi-Fi passwords are never taken or shown: a new or reset Wi-Fi network gets a random temporary password, and the real
one is set in the controller's web UI. Reads need QUERY, changes CONFIGURE.
On Omada, a network isolation flag (use a block rule instead), a "guest" network type, switching IPv6 on, and WPA2/WPA3
mixed mode are not available through the API and are refused. Rules are gateway ACLs (the gateway routes between the
VLANs): LAN to LAN between your networks, LAN to WAN towards the internet. Refused with the reason: the gateway itself as
a destination (no API option for its own addresses), one device by MAC (give its address), a Wi-Fi network as the
source, rules that also match replies, schedules (the omada_ time-range tools do those) and port ranges. Port
profiles are created in the controller web UI; net_assignPort sets a port's own networks (on controller 6.3 profiles
usually set none, and a port can't be put back on its profile's). The mDNS repeater is the controller's
one gateway mDNS rule: create it once in the web UI (with the services to repeat), then change it here; access point
mDNS rules, several rules or a one-way rule are shown as foreign and left to the web UI.
On a Ruijie / Reyee router (2.5.0, read-only, mapped on a RG-EG105G-V3 with ReyeeOS 2.324) the net_ list tools show
its LAN networks, the devices it sees on its LAN right now (named by their address lease), DHCP reservations, its
ports (the WAN port as the protected uplink) and its access-control rules; rules the model can't say faithfully (a
source "anywhere", source ports, IPv6, user groups, schedules, only some connection states, an interface restriction the
model can't carry, ports for TCP or UDP only) are shown as foreign.
Every change but a firmware upgrade (2.5.1: the version the router itself is offered, the same as its page's Online
Upgrade) is refused for now: reservations and rules come next, then networks. It talks to the router's local web
API with its admin password; use https:// with RUIJIE_CERT_SHA256 (the router's own login page hides the password
with a key that is shipped in the page, so only HTTPS really protects it, and the router's self-signed certificate is
best pinned: the RG-EG105G-V3 ships OpenSSL's sample identity, valid until 2122, likely the same on every unit). A refused login is never retried, because wrong passwords lock
the router's login: the Ruijie tools then refuse until the setting is fixed and the server restarted.
AI Tools (1)
Infrastructure Tools (1)
MCP Resources
Prerequisites
- Node.js 20+ (CI tests Node 20, 22, 24 and 26; the Docker image runs Node 24) - for npm/npx methods
- npm 10.8+ - 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
Getting Your Home Assistant Token
- 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!)
Environment Variables
Required
Optional - Home Assistant
Optional - MCP Server
Optional - HTTP Mode
Optional - Chat face (OpenAPI/REST surface)
The server also serves an OpenAPI/REST face (/openapi.json + /api/*) for chat UIs
like Open WebUI. /openapi.json needs no token, so it is served on the LAN only: a request that came through
Cloudflare (it carries CF-Connecting-IP or CF-Ray) gets a 404, so point the chat UI at the server's LAN address. 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.json as POST /api/tools/<name>
and dispatch through the same handlers, validation, and RBAC as the MCP face.
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 lookupexp(optional): Expiration timestamp
Permission System
The server uses role-based access control with binary permission masks:
Predefined Roles:
Configuration Example:
{
"users": [
{ "sub": "[email protected]", "role": "admin" },
{ "sub": "[email protected]", "role": "operator" },
{ "sub": "[email protected]", "role": "readonly" }
],
"defaultRole": "NONE"
}
Set via environment variable (escape quotes for shell):
MCP_PERMISSIONS_CONFIG='{"users":[{"sub":"admin","role":"admin"}],"defaultRole":"NONE"}'
Recommended: defaultRole: "NONE" plus one users entry per client. defaultRole applies to
every validly signed token whose sub is not listed — a non-NONE default silently gives unmapped
clients real access. The server logs a warning at startup when defaultRole grants anything. Map each
client (Open WebUI, n8n, agents…) explicitly before switching an existing deployment to NONE.
Clients only see the tools they may use: tools/list is filtered by the caller's permissions, so a
readonly token is never offered control or admin tools (calls are still checked per tool).
Optional - AI Provider
Optional - Omada Network Controller
Optional - Ruijie / Reyee Router
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": "qwen3:14b"
}
}
}
}
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
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
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:
- ai-agent-safety-monitor - Critical safety monitoring every 5 minutes
Importing Workflows
Method 1: n8n UI
- Open n8n:
http://127.0.0.1:5678 - Click Workflows → Import from File
- Select JSON file from
n8n-files/ - 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:
- Start server in HTTP mode
- Configure client to use
http://localhost:3000/mcp - Set transport to Streamable HTTP (MCP 2025-03-26)
- 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--headervalue. A config like"Authorization: Bearer ${MCP_AUTH_TOKEN}"with a matchingenvblock does not work 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.)
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-gatewayto 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)
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
.envsecurely (contains access token) - Never commit
.envto version control - Set
.envpermissions:chmod 600 .env - Use
HA_STRICT_SSL=truefor HTTPS in production - Rotate access tokens periodically
- Restrict
MCP_HTTP_ALLOWED_ORIGINS(avoid wildcard*) - Bind to
127.0.0.1for 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
.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
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.
Troubleshooting
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 /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
- Verify URL - Try accessing
http://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 - Try
HA_STRICT_SSL=falsefor testing
AI Analysis Not Working
- Verify Ollama is running -
curl http://your-ollama-url:11434/api/tags - Check model is available - Ensure the model in
AI_MODEL(defaultqwen3:14b) is pulled:ollama pull qwen3:14b - Set AI_PROVIDER - Must be set to
ollama(notnone)
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
License
MIT
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
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.