# homeassistant-ai/ha-mcp architecture

> Architecture diagram of the GitHub repository homeassistant-ai/ha-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/homeassistant-ai/ha-mcp
- Repository: https://github.com/homeassistant-ai/ha-mcp

## Overview

HA-MCP is an MCP server that lets AI clients control and inspect Home Assistant. The documented primary workflow is to configure the integration, enable a connection method, copy its URL, and connect an AI client; requests then reach Home Assistant through MCP tools. The README also documents an admin panel, optional authentication, backups, themes, and opt-in file/YAML tools. Some subsystem links below are dashed because the relevant implementation was not sampled.

Main entry points: [`src/ha_mcp/_vendor/fastmcp/server/server.py`](https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/_vendor/fastmcp/server/server.py) (MCP server core), [`custom_components/ha_mcp_tools/embedded_entry.py`](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/embedded_entry.py) (Server entry), [`custom_components/ha_mcp_tools/ui_panel.py`](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/ui_panel.py) (Settings panel), [`custom_components/ha_mcp_tools/mcp_webhook.py`](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/mcp_webhook.py) (Webhook access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and access"]
  node_integration_setup["Integration setup<br/>[config_flow.py]"]
  node_server_entry["Server entry<br/>[embedded_entry.py]"]
  node_webhook["Webhook access<br/>[mcp_webhook.py]"]
  node_oauth["OAuth access<br/>[oauth_dcr.py]"]
end

subgraph group_runtime["MCP runtime"]
  node_embedded_server["Embedded server<br/>[embedded_server.py]"]
  node_mcp_server["MCP server core<br/>[server.py]"]
  node_http_transport["HTTP transport<br/>[http.py]"]
  node_http_sessions["HTTP sessions"]
  node_oauth_routes["OAuth routes<br/>[routes.py]"]
end

subgraph group_ha_tools["Home Assistant tools"]
  node_ha_commands["HA commands<br/>[call_service.py]"]
  node_assist_pipelines["Assist pipelines"]
  node_dashboard_tools["Dashboard tools<br/>[dashboard_edit.py]"]
  node_file_yaml["File and YAML tools<br/>[yaml_rt.py]"]
  node_service_catalog["Service catalog<br/>[services.py]"]
end

subgraph group_admin["Administration"]
  node_settings_panel["Settings panel<br/>[ui_panel.py]"]
  node_backup_manager["Backup manager<br/>[backup_manager.py]"]
  node_oauth_callbacks["OAuth callback settings"]
end

node_admin_user(("HA administrator"))
node_ai_client(("AI client"))
node_home_assistant["Home Assistant"]

node_admin_user -->|"configures"| node_integration_setup
node_integration_setup -.->|"creates entry"| node_server_entry
node_server_entry -.->|"starts"| node_embedded_server
node_server_entry -.->|"enables access"| node_webhook
node_ai_client -->|"connects"| node_webhook
node_ai_client -->|"connects locally"| node_embedded_server
node_webhook -.->|"forwards requests"| node_mcp_server
node_embedded_server -.->|"hosts"| node_mcp_server
node_mcp_server -.->|"serves over HTTP"| node_http_transport
node_http_transport -.->|"manages sessions"| node_http_sessions
node_mcp_server -.->|"registers auth"| node_oauth_routes
node_oauth -.->|"authenticates"| node_oauth_routes
node_mcp_server -.->|"exposes tools"| node_ha_commands
node_mcp_server -.->|"exposes tools"| node_assist_pipelines
node_mcp_server -.->|"exposes tools"| node_dashboard_tools
node_mcp_server -.->|"exposes optional tools"| node_file_yaml
node_ha_commands -.->|"calls services"| node_home_assistant
node_assist_pipelines -.->|"manages pipelines"| node_home_assistant
node_dashboard_tools -.->|"manages dashboards"| node_home_assistant
node_file_yaml -.->|"edits configuration"| node_home_assistant
node_admin_user -->|"manages server"| node_settings_panel
node_settings_panel -.->|"manages backups"| node_backup_manager
node_settings_panel -.->|"edits callbacks"| node_oauth_callbacks
node_service_catalog -->|"describes services"| node_ha_commands

click node_integration_setup "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/config_flow.py"
click node_server_entry "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/embedded_entry.py"
click node_embedded_server "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/embedded_server.py"
click node_webhook "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/mcp_webhook.py"
click node_oauth "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/oauth_dcr.py"
click node_mcp_server "https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/_vendor/fastmcp/server/server.py"
click node_http_transport "https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/_vendor/fastmcp/server/http.py"
click node_http_sessions "https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/_vendor/mcp/server/streamable_http_manager.py"
click node_oauth_routes "https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/_vendor/mcp/server/auth/routes.py"
click node_ha_commands "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/websocket_api/call_service.py"
click node_assist_pipelines "https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/tools/tools_assist_pipeline.py"
click node_dashboard_tools "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/dashboard_edit.py"
click node_file_yaml "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/yaml_rt.py"
click node_settings_panel "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/ui_panel.py"
click node_backup_manager "https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/backup_manager.py"
click node_oauth_callbacks "https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/settings_ui/_handlers_oauth_callbacks.py"
click node_service_catalog "https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/websocket_api/services.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_integration_setup,node_server_entry,node_webhook,node_oauth,node_ai_client toneBlue
class node_embedded_server,node_mcp_server,node_http_transport,node_http_sessions,node_oauth_routes toneAmber
class node_ha_commands,node_assist_pipelines,node_dashboard_tools,node_file_yaml,node_service_catalog toneMint
class node_settings_panel,node_backup_manager,node_oauth_callbacks toneRose
class node_admin_user,node_home_assistant toneIndigo
```

## Components

### Setup and access

- [Integration setup](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/config_flow.py): `custom_components/ha_mcp_tools/config_flow.py`
- [Server entry](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/embedded_entry.py): `custom_components/ha_mcp_tools/embedded_entry.py`
- [Webhook access](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/mcp_webhook.py): `custom_components/ha_mcp_tools/mcp_webhook.py`
- [OAuth access](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/oauth_dcr.py): `custom_components/ha_mcp_tools/oauth_dcr.py`

### MCP runtime

- [Embedded server](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/embedded_server.py): `custom_components/ha_mcp_tools/embedded_server.py`
- [MCP server core](https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/_vendor/fastmcp/server/server.py): `src/ha_mcp/_vendor/fastmcp/server/server.py`
- [HTTP transport](https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/_vendor/fastmcp/server/http.py): `src/ha_mcp/_vendor/fastmcp/server/http.py`
- [HTTP sessions](https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/_vendor/mcp/server/streamable_http_manager.py): `src/ha_mcp/_vendor/mcp/server/streamable_http_manager.py`
- [OAuth routes](https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/_vendor/mcp/server/auth/routes.py): `src/ha_mcp/_vendor/mcp/server/auth/routes.py`

### Home Assistant tools

- [HA commands](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/websocket_api/call_service.py): `custom_components/ha_mcp_tools/websocket_api/call_service.py`
- [Assist pipelines](https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/tools/tools_assist_pipeline.py): `src/ha_mcp/tools/tools_assist_pipeline.py`
- [Dashboard tools](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/dashboard_edit.py): `custom_components/ha_mcp_tools/dashboard_edit.py`
- [File and YAML tools](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/yaml_rt.py): `custom_components/ha_mcp_tools/yaml_rt.py`
- [Service catalog](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/websocket_api/services.py): `custom_components/ha_mcp_tools/websocket_api/services.py`

### Administration

- [Settings panel](https://github.com/homeassistant-ai/ha-mcp/blob/master/custom_components/ha_mcp_tools/ui_panel.py): `custom_components/ha_mcp_tools/ui_panel.py`
- [Backup manager](https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/backup_manager.py): `src/ha_mcp/backup_manager.py`
- [OAuth callback settings](https://github.com/homeassistant-ai/ha-mcp/blob/master/src/ha_mcp/settings_ui/_handlers_oauth_callbacks.py): `src/ha_mcp/settings_ui/_handlers_oauth_callbacks.py`

### Other components

- **HA administrator**
- **AI client**
- **Home Assistant**

## Connections

- HA administrator → Integration setup: configures
- Integration setup → Server entry: creates entry
- Server entry → Embedded server: starts
- Server entry → Webhook access: enables access
- AI client → Webhook access: connects
- AI client → Embedded server: connects locally
- Webhook access → MCP server core: forwards requests
- Embedded server → MCP server core: hosts
- MCP server core → HTTP transport: serves over HTTP (evidence: `src/ha_mcp/_vendor/fastmcp/server/http.py`)
- HTTP transport → HTTP sessions: manages sessions (evidence: `src/ha_mcp/_vendor/fastmcp/server/http.py`)
- MCP server core → OAuth routes: registers auth
- OAuth access → OAuth routes: authenticates
- MCP server core → HA commands: exposes tools
- MCP server core → Assist pipelines: exposes tools
- MCP server core → Dashboard tools: exposes tools
- MCP server core → File and YAML tools: exposes optional tools
- HA commands → Home Assistant: calls services
- Assist pipelines → Home Assistant: manages pipelines
- Dashboard tools → Home Assistant: manages dashboards
- File and YAML tools → Home Assistant: edits configuration
- HA administrator → Settings panel: manages server
- Settings panel → Backup manager: manages backups
- Settings panel → OAuth callback settings: edits callbacks
- Service catalog → HA commands: describes services (evidence: `custom_components/ha_mcp_tools/websocket_api/services.py`)
