Overview

The Home Assistant MCP Server provides a lightweight bridge between Home Assistant and clients that speak the Model Context Protocol (MCP). It exposes Home Assistant entities (lights, switches, sensors, etc.) through a single MCP-compatible interface so you can view states and send commands from one centralized client or agent. This is useful when integrating Home Assistant into multi-agent systems, conversational assistants, or custom dashboards that rely on MCP for model-driven context and control.

The server handles authentication with Home Assistant, entity discovery, state updates, and service calls. Clients communicate with the MCP server using a small set of message types (list, get, call, subscribe) instead of talking directly to Home Assistant’s REST or websocket APIs. That reduces complexity for client implementations and centralizes access control and throttling.

Features

Exposes Home Assistant entities (lights, switches, sensors, binary_sensors, covers, climate, etc.) via MCP
Fetch entity lists and current states
Call Home Assistant services for entities (turn_on, turn_off, toggle, set_temperature, etc.)
Subscribe to state changes for live updates over the MCP channel
Centralized configuration for Home Assistant URL and long-lived access token
Lightweight server suitable for local deployment or containerization
Simple JSON message format to integrate with MCP-aware tools and agents

Installation / Configuration

Requirements: Python 3.9+ and a Home Assistant instance with a long-lived access token.

Clone and install

git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure environment variables (example)

export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="LONG_LIVED_ACCESS_TOKEN"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8765"

Alternatively, create a .env file:

HA_URL=http://homeassistant.local:8123
HA_TOKEN=YOUR_LONG_LIVED_TOKEN
MCP_HOST=0.0.0.0
MCP_PORT=8765

Run the server

If the project exposes an ASGI app (common pattern):

uvicorn homeassistant_mcp.app:app --host $MCP_HOST --port $MCP_PORT

Or run the included entrypoint script:

python -m homeassistant_mcp.server

Example configuration options (JSON)

{
  "ha_url": "http://homeassistant.local:8123",
  "ha_token": "<long-lived-token>",
  "allowed_entities": ["light.living_room", "switch.garage"],
  "update_interval_seconds": 5
}

Available Resources

GitHub repository (source and issues): https://github.com/tevonsb/homeassistant-mcp
Typical MCP messages supported (direction: client → server)

Message	Description	Example payload
entity.list	Return all available entities (optionally filtered)	{ “filter”: “light.*” }
entity.get	Get current state for one entity	{ “entity_id”: “light.kitchen” }
entity.call	Call a Home Assistant service for an entity	{ “entity_id”: “switch.fan”, “service”: “turn_on”, “service_data”: {} }
entity.subscribe	Subscribe to state changes for one or more entities	{ “entities”: [“sensor.temp”] }

HTTP endpoints (if provided)
- GET /entities — list entities
- GET /entities/{entity_id} — get entity state
- POST /entities/{entity_id}/call — call a service for an entity
Example Python client (requests)

import requests, os
BASE = "http://localhost:8765"
r = requests.get(f"{BASE}/entities")
print(r.json())
# Call a service
payload = {"service": "turn_on", "service_data": {}}
requests.post(f"{BASE}/entities/light.kitchen/call", json=payload)

Use Cases

Centralized agent control: Use a single MCP-aware assistant to monitor and control Home Assistant devices across multiple homes or installations. The assistant only needs to implement MCP, not Home Assistant protocols.
Conversation-driven automations: Feed live entity states to an LLM or rule engine via MCP so it can make context-aware decisions (e.g., “Turn off all lights in empty rooms”).
Dashboard aggregation: Build a custom frontend that subscribes to relevant entities and displays statuses and controls without using Home Assistant’s frontend.
Controlled access for external systems: Limit which entities and services are exposed to external agents by configuring allowed_entities and centralizing auditing in the MCP server.
Testing and simulation: Mock Home Assistant entities for development by running the MCP server in a sandbox mode or with test fixtures.

Practical examples

Turn on a light via HTTP

curl -X POST "http://localhost:8765/entities/light.living_room/call" \
  -H "Content-Type: application/json" \
  -d '{"service":"turn_on","service_data":{"brightness":200}}'

Subscribe to updates (WebSocket / MCP client)
- Connect and send a subscribe message for sensor updates. The server will push state change events to the client as they occur.

For source code, issues, and contribution guidelines visit the project repository: https://github.com/tevonsb/homeassistant-mcp.

Home Assistant MCP Server: Control Lights, Switches, Sensors