Home Assistant MCP Architecture

The Home Assistant MCP (Model Context Protocol) server provides AI agents with complete programmatic control over a Home Assistant smart home installation. It exposes 40+ MCP tools across 30+ tool modules that allow an AI client to query entity states, control devices, manage automations, read sensor history, configure dashboards, manage integrations, and interact with virtually every Home Assistant subsystem.

The server communicates with Home Assistant via its REST API and WebSocket API, translating MCP tool calls into HA service calls, state queries, and configuration operations. It supports multiple transport modes: stdio (for Claude Code / CLI), SSE (Server-Sent Events), and HTTP (Streamable HTTP for web-based MCP clients).

Upstream project: github.com/homeassistant-ai/ha-mcp (MIT license, by Julien). Version 7.1.0. Python 3.13, FastMCP 3.1.1 framework.

Package Version

7.1.0

Tool Modules

30+

Transport Modes

Runtime

Python 3.13

Framework

FastMCP 3.1.1

Container Port

8086

2. Runtime Architecture

Diagram A: Runtime Request Flow

Request Flow

An MCP client (Claude Code via stdio, or a web client via HTTP/SSE on port 8086) sends a tool call to the HA MCP Server.
The server authenticates the request using the HOMEASSISTANT_TOKEN (long-lived access token) or OAuth2 flow.
The appropriate tool module processes the request, delegating to the REST Client (for state queries, service calls, config operations) or the WebSocket Client (for real-time subscriptions, event streaming, template rendering).
The client modules call the Home Assistant API at https://homeassistant.sanchezfamily.ca.
Results are transformed, filtered (via transforms/ and utils/), and returned as structured MCP responses.

3. Component Classification

Component	Classification	Role
`server.py`	Primary	Main MCP server — registers all tools, handles routing, manages lifecycle
`__main__.py`	Primary	Entry points for all transport modes (stdio, SSE, HTTP, OAuth)
`client/rest_client.py`	Primary	Async HTTP client for Home Assistant REST API (httpx-based)
`client/websocket_client.py`	Primary	Persistent WebSocket connection for real-time HA communication
`client/websocket_listener.py`	Secondary	Event listener for WebSocket state change subscriptions
`tools/` (30+ modules)	Primary	MCP tool implementations — entities, devices, automations, dashboards, etc.
`auth/provider.py`	Secondary	OAuth2 authentication provider for HA authorization flow
`auth/consent_form.py`	Secondary	HTML consent form for OAuth authorization UI
`config.py`	Secondary	Pydantic settings model — reads env vars for HA URL, token, options
`errors.py`	Secondary	Structured error codes and error response factory
`transforms/`	Auxiliary	Response transforms — categorized search result formatting
`utils/`	Auxiliary	Fuzzy search, domain handlers, operation manager, Python sandbox, usage logger
`resources/`	Auxiliary	Static resources — dashboard guide, card types, HA best-practices skill

4. Tool Modules

The tools/ directory contains 30+ Python modules, each registering one or more MCP tools with the server. These are grouped by Home Assistant domain.

Module	Size	Domain
`tools_config_dashboards.py`	70KB	Dashboard CRUD, card management, view configuration
`tools_config_helpers.py`	53KB	Input helpers (boolean, number, text, select, datetime)
`tools_registry.py`	48KB	Entity and device registry queries
`smart_search.py`	47KB	Intelligent entity/device search with fuzzy matching
`tools_search.py`	36KB	General search across all HA domains
`tools_entities.py`	33KB	Entity state queries, filtering, bulk operations
`tools_hacs.py`	32KB	HACS (Home Assistant Community Store) management
`tools_history.py`	30KB	Entity state history, statistics, trend analysis
`device_control.py`	28KB	Direct device control (lights, switches, covers, climate, media)
`tools_updates.py`	28KB	System and integration update management
`tools_config_automations.py`	26KB	Automation CRUD, enable/disable, trigger
`tools_bug_report.py`	24KB	Diagnostic bug report generation
`tools_resources.py`	23KB	MCP resource endpoints (documentation, guides)
`tools_config_entry_flow.py`	21KB	Integration setup flows (config entries)
`tools_todo.py`	20KB	To-do list management
`tools_traces.py`	21KB	Automation and script trace inspection
`tools_utility.py`	21KB	Template rendering, YAML validation, utility operations
`tools_areas.py`	18KB	Area/floor/room management
`tools_filesystem.py`	18KB	HA config file operations (read/write YAML)
`backup.py`	18KB	HA backup creation and management
`tools_integrations.py`	16KB	Integration listing and management
`tools_config_scripts.py`	15KB	Script CRUD and execution
`tools_calendar.py`	15KB	Calendar entity queries and event management
`tools_system.py`	15KB	System info, restart, check config, logs
`best_practice_checker.py`	15KB	Validates automations against HA best practices
`tools_service.py`	14KB	HA service call execution
`tools_blueprints.py`	14KB	Automation blueprint management
`tools_zones.py`	13KB	Zone management (presence detection)
`tools_addons.py`	13KB	Supervisor add-on management
`tools_groups.py`	12KB	Entity group management
`tools_mcp_component.py`	12KB	MCP component self-inspection
`tools_labels.py`	10KB	Label management for entities and devices
`tools_config_info.py`	11KB	Configuration validation and diagnostics
`tools_services.py`	11KB	Service domain listing and discovery
`tools_camera.py`	6KB	Camera snapshot capture
`tools_voice_assistant.py`	7KB	Voice assistant pipeline control

5. Public Interfaces (MCP Tools)

The server exposes MCP tools organized by domain. The following is a representative catalog of the key tool categories.

Entity Control & State

Tool Category	Module	Capabilities
Entity Queries	`tools_entities`	Get entity states, filter by domain/area/label, bulk state retrieval
Device Control	`device_control`	Turn on/off, set brightness, color, temperature, position, media playback
Service Calls	`tools_service`	Call any HA service with arbitrary parameters
Smart Search	`smart_search`	Fuzzy entity/device search with natural language queries

Configuration & Automation

Tool Category	Module	Capabilities
Automations	`tools_config_automations`	Create, update, delete, enable/disable, trigger automations
Scripts	`tools_config_scripts`	CRUD for scripts, execute with parameters
Dashboards	`tools_config_dashboards`	Create/edit dashboards, cards, views (Lovelace YAML)
Helpers	`tools_config_helpers`	Create/manage input_boolean, input_number, input_text, input_select, etc.
Blueprints	`tools_blueprints`	Import, list, and manage automation blueprints

Monitoring & History

Tool Category	Module	Capabilities
State History	`tools_history`	Query entity history over time ranges, statistics, trends
Traces	`tools_traces`	Inspect automation/script execution traces for debugging
System Info	`tools_system`	HA version, uptime, restart, check config, view logs
Bug Reports	`tools_bug_report`	Generate diagnostic reports with system state

Organization & Management

Tool Category	Module	Capabilities
Areas & Zones	`tools_areas`, `tools_zones`	Manage rooms/floors, presence zones
Registry	`tools_registry`	Device/entity registry queries, rename, disable
Integrations	`tools_integrations`	List configured integrations, config entry details
Labels & Groups	`tools_labels`, `tools_groups`	Tag entities, manage groups
HACS	`tools_hacs`	Community store: browse, install, update custom components
Updates	`tools_updates`	Check for and install HA core, OS, and integration updates
Backups	`backup`	Create and manage HA backups
Add-ons	`tools_addons`	Supervisor add-on lifecycle (start, stop, install)

Specialized Tools

Tool Category	Module	Capabilities
Calendar	`tools_calendar`	Query calendar events, create events
Camera	`tools_camera`	Capture camera snapshots
To-Do	`tools_todo`	To-do list item CRUD
Voice Assistant	`tools_voice_assistant`	Voice pipeline control
Filesystem	`tools_filesystem`	Read/write HA configuration files (YAML)
Utility	`tools_utility`	Template rendering, YAML validation
Best Practices	`best_practice_checker`	Validate automations against HA best practices

Transport Endpoints

Transport	Entry Point	Use Case
stdio	`ha-mcp`	Claude Code, CLI-based MCP clients
SSE	`ha-mcp-sse`	Server-Sent Events for streaming clients
HTTP (Streamable)	`ha-mcp-web` (port 8086, path `/mcp`)	Web-based MCP clients, deployed mode
OAuth	`ha-mcp-oauth`	OAuth2 authorization code flow

6. Repository Structure

/app/
  fastmcp.json                 # FastMCP stdio config
  fastmcp-http.json            # FastMCP HTTP deployment config (port 8086, /mcp)
  .venv/                       # Python 3.13 virtual environment
  src/
    ha_mcp/
      __init__.py              # Package metadata (v7.1.0)
      __main__.py              # Entry points: main(), main_web(), main_sse(), main_oauth()
      server.py                # HomeAssistantSmartMCPServer - core MCP server class
      config.py                # Pydantic Settings model (env var parsing)
      errors.py                # Error codes and response factory
      smoke_test.py            # Connection smoke test utility
      auth/
        provider.py            # OAuth2 auth provider for HA
        consent_form.py        # HTML consent form renderer
      client/
        rest_client.py         # HomeAssistantClient (httpx async)
        websocket_client.py    # WebSocket client for HA WS API
        websocket_listener.py  # Event subscription listener
      tools/
        (30+ modules)          # MCP tool implementations by HA domain
        device_control.py      # DeviceControlTools class
        smart_search.py        # SmartSearchTools class
        registry.py            # Tool registry management
        helpers.py             # Shared tool helper functions
        enhanced.py            # Enhanced tool wrappers
        util_helpers.py        # Common utility functions for tools
      transforms/
        categorized_search.py  # Search result categorization/formatting
      utils/
        domain_handlers.py     # HA domain-specific logic
        fuzzy_search.py        # Fuzzy string matching for entity names
        operation_manager.py   # Rate limiting, operation tracking
        python_sandbox.py      # Sandboxed Python execution
        usage_logger.py        # Tool usage logging/analytics
      resources/
        card_types.json        # Dashboard card type definitions
        dashboard_guide.md     # Lovelace dashboard creation guide
        skills-vendor/         # HA best practices skill (Claude plugin)

7. Deployment & Operations

Docker Compose

services:
  ha-mcp:
    image: ghcr.io/homeassistant-ai/ha-mcp:latest
    container_name: ha-mcp
    restart: unless-stopped
    env_file:
      - /home/rod/.env
    command: ["ha-mcp-web"]
    ports:
      - "10.0.1.6:8086:8086"

Environment Variables

Variable	Required	Description
`HOMEASSISTANT_URL`	Yes	Home Assistant base URL (e.g., `https://homeassistant.sanchezfamily.ca`)
`HOMEASSISTANT_TOKEN`	Yes	Long-lived access token for HA API authentication

Network Binding

The container binds port 8086 to 10.0.1.6 only (LAN interface). It is not published to all interfaces. The MCP endpoint is available at http://10.0.1.6:8086/mcp.

Operational Commands

# Check container status
docker ps | grep ha-mcp

# View logs
docker logs -f ha-mcp

# Restart
cd /home/rod/_rod/_hosting/docker/ha-mcp
docker compose restart

# Smoke test
docker exec ha-mcp ha-mcp-smoke-test

# Test MCP endpoint
curl -s http://10.0.1.6:8086/mcp

Claude Code Integration

To use this MCP server with Claude Code, add it to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "ha-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "ha-mcp", "ha-mcp"],
      "env": {}
    }
  }
}

This uses the stdio transport by running the ha-mcp entry point inside the running container. Alternatively, use the HTTP transport at http://10.0.1.6:8086/mcp.

8. Dependencies

Package	Version	Purpose
`fastmcp`	3.1.1	MCP server framework (tool registration, transport handling)
`httpx`	0.28.1	Async HTTP client for Home Assistant REST API calls
`websockets`	16.0	WebSocket client for HA real-time event subscriptions
`pydantic`	2.12.5	Settings validation, data models, type safety
`python-dotenv`	1.2.2	Environment variable loading from .env files
`truststore`	0.10.4	System certificate store integration for TLS
`cryptography`	46.0.5	Cryptographic operations for OAuth2 token handling
`jq`	1.11.0	JSON query/filter for response processing (Linux only)

External Service Dependencies

Service	Address	Protocol	Required
Home Assistant	`homeassistant.sanchezfamily.ca`	HTTPS (REST + WebSocket)	Yes

9. Constraints & Risks

Item	Severity	Description
Token in .env	Medium	The `HOMEASSISTANT_TOKEN` is a long-lived access token stored in `/home/rod/.env`. It grants full API access to Home Assistant. Rotate periodically.
Full HA API access	Medium	The MCP server can call any HA service, including destructive operations (restart, config changes, device removal). The tool set has no built-in permission scoping beyond what HA provides.
Python 3.13 requirement	Low	Requires Python >=3.13, <3.14. Managed by the container image, so no host impact.
Network dependency	Low	Depends on Home Assistant being reachable at the configured URL. If HA is down, all tools return connection errors.
No Traefik route	Info	Currently bound to `10.0.1.6:8086` only. No `dynamic.yml` router or DNS entry. Access is LAN-direct only. Add a Traefik route if external or `.home` domain access is needed.
Env file leaks other secrets	Medium	The `env_file` is `/home/rod/.env` which also contains PVE tokens and SSH keys. These are injected into the container as environment variables unnecessarily. Consider using a dedicated `.env` with only `HOMEASSISTANT_URL` and `HOMEASSISTANT_TOKEN`.

Generated by /repo-architecture v2.0.0 on 2026-03-22. This document is auto-generated — regenerate after significant changes.