Home Assistant MCP Server

Translates natural language requests from LLMs into Home Assistant service calls through the Model Context Protocol (MCP) interface. The server exposes a tool registry that LLMs can discover and invoke, with each tool mapping to Home Assistant entity services (lights, climate, switches, covers, locks, vacuums, media players, fans). Requests flow through Express/LiteMCP servers, pass through token-based security validation middleware, and route to Home Assistant REST API endpoints with long-lived access tokens.

Establishes persistent Server-Sent Events (SSE) connections that stream Home Assistant state changes to connected clients in real-time. The server maintains WebSocket connections to Home Assistant, listens for state_changed events, and broadcasts updates to all subscribed SSE clients with entity_id, old_state, new_state, and timestamp metadata. This enables LLM agents to maintain current awareness of home state without polling.

Implements entity type-specific control logic that maps generic control requests to Home Assistant service calls with appropriate parameters. For example, light control maps brightness/color requests to light.turn_on service with brightness/rgb_color parameters; climate control maps temperature requests to climate.set_temperature service. Each entity type (light, climate, switch, cover, lock, vacuum, media_player, fan) has dedicated control logic that validates parameters and constructs correct service calls. This abstraction hides Home Assistant service complexity from LLMs.

Provides endpoints to query current state of Home Assistant entities (devices, sensors, automations) and returns structured JSON responses with entity_id, state, attributes, and last_updated metadata. The server maintains a cached view of all Home Assistant entities and supports filtering by entity type (light, climate, switch, sensor, etc.). Responses are formatted to be LLM-friendly with human-readable state values and attribute descriptions.

Enables creation, modification, triggering, and management of Home Assistant automations and scenes through MCP tools. Supports complex automation configurations including triggers (time, state, event), conditions (templates, state checks), and actions (service calls, scene activation). The server translates LLM requests into Home Assistant automation YAML/JSON and manages automation lifecycle (enable/disable/trigger). Scenes can be created from current state snapshots or manually configured.

Provides tools to browse, install, uninstall, start, stop, and configure Home Assistant add-ons and custom integrations through Home Assistant Community Store (HACS). The server exposes add-on discovery endpoints, installation status tracking, and configuration management. Supports both official Home Assistant add-ons and community-maintained packages. Configuration changes trigger add-on restarts and validate settings before application.

Implements security middleware that validates long-lived access tokens on all incoming requests before routing to Home Assistant. Tokens are validated against Home Assistant's token store, and requests without valid tokens are rejected with 401 Unauthorized responses. The middleware applies to all endpoints (device control, state queries, automation management) and prevents unauthorized access to Home Assistant. Token validation happens synchronously before request processing.

Maintains a registry of all available MCP tools (device control, state queries, automation management, add-on management) with JSON Schema definitions for parameters and return types. The tool registry is exposed through MCP protocol endpoints, enabling LLMs to discover available tools, understand parameter requirements, and validate tool invocations against schemas. Each tool includes description, parameter schema, and example usage. LLMs use this registry to determine which tools to invoke for user requests.

Implements dual server transports for MCP protocol support: Express.js for HTTP/REST endpoints and LiteMCP for lightweight MCP-specific protocol handling. Both transports share the same underlying tool implementations and Home Assistant integration layer. Express handles traditional HTTP requests and SSE connections, while LiteMCP provides optimized MCP protocol support. Clients can choose transport based on their requirements (HTTP compatibility vs MCP protocol optimization).

Routes all device control, state query, and automation management requests to Home Assistant REST API endpoints using long-lived access tokens. The MCP server acts as a stateless proxy that translates tool invocations into Home Assistant service calls, maintaining no persistent state about devices or automations. Each request is independently validated, routed to the appropriate Home Assistant endpoint, and responses are returned to the client. This architecture enables horizontal scaling and simplifies deployment.

Establishes persistent WebSocket connections to Home Assistant and subscribes to state_changed events. The server maintains these connections internally and uses them to power SSE streaming and real-time state awareness. WebSocket subscriptions are established using Home Assistant's WebSocket API with long-lived tokens. The server handles connection lifecycle (reconnection on failure, heartbeat/ping-pong), event filtering, and broadcasts updates to connected SSE clients.