How homeassistant-ai/ha-mcp works
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: server.py MCP server core · embedded_entry.py Server entry · ui_panel.py Settings panel · mcp_webhook.py Webhook access
Components 20
Setup and access
- Integration setup
custom_components/ha_mcp_tools/config_flow.py - Server entry
custom_components/ha_mcp_tools/embedded_entry.py - Webhook access
custom_components/ha_mcp_tools/mcp_webhook.py - OAuth access
custom_components/ha_mcp_tools/oauth_dcr.py
MCP runtime
- Embedded server
custom_components/ha_mcp_tools/embedded_server.py - MCP server core
src/ha_mcp/_vendor/fastmcp/server/server.py - HTTP transport
src/ha_mcp/_vendor/fastmcp/server/http.py - HTTP sessions
src/ha_mcp/_vendor/mcp/server/streamable_http_manager.py - OAuth routes
src/ha_mcp/_vendor/mcp/server/auth/routes.py
Home Assistant tools
- HA commands
custom_components/ha_mcp_tools/websocket_api/call_service.py - Assist pipelines
src/ha_mcp/tools/tools_assist_pipeline.py - Dashboard tools
custom_components/ha_mcp_tools/dashboard_edit.py - File and YAML tools
custom_components/ha_mcp_tools/yaml_rt.py - Service catalog
custom_components/ha_mcp_tools/websocket_api/services.py
Administration
- Settings panel
custom_components/ha_mcp_tools/ui_panel.py - Backup manager
src/ha_mcp/backup_manager.py - OAuth callback settings
src/ha_mcp/settings_ui/_handlers_oauth_callbacks.py
Other components
- HA administrator
- AI client
- Home Assistant
Connections 24
- 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
src/ha_mcp/_vendor/fastmcp/server/http.py - HTTP transport → HTTP sessions: manages sessions
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
custom_components/ha_mcp_tools/websocket_api/services.py