home-assistant-agent¶
Home Assistant REST + WebSocket API, MCP Server, and A2A Agent for the agent-utilities ecosystem — control lights, switches, media players, calendars, and query historical state across your smart home.
Official documentation
This site is the canonical reference for home-assistant-agent, maintained
alongside every release.
Overview¶
home-assistant-agent wraps the Home Assistant REST and WebSocket API surface with
typed, deterministic MCP tools and an optional Pydantic-AI agent server. It provides:
HomeAssistantApi— a unified REST + WebSocket client over the Home Assistant API (configuration, states, services, events, history, logbook, calendars, and system health).- Action-routed MCP tools across eleven domains — Config, States, Services, Events, History, Logbook, Calendar, Panels, Voice, Entities, and System — each toggled independently by environment flag.
- An optional A2A agent server (
home-assistant-agent) that wires the same tool surface into a Pydantic-AI graph agent with an embedded web UI.
Every tool registration is governed by an environment flag, so the server exposes only the capabilities you enable and remains inactive when credentials are absent.
Explore the documentation¶
- Installation — pip, source, extras, and the prebuilt Docker image.
- Deployment — run the MCP server, the agent server, Docker Compose, Caddy + Technitium.
- Usage — the MCP tools, the
HomeAssistantApiclient, and the CLI. - Backing Platform — deploy Home Assistant with Docker.
- Overview — architecture, tool surface, and ecosystem role.
- Concepts — the
CONCEPT:HASS-*registry.
Quick start¶
Connect it to a Home Assistant instance:
export HOME_ASSISTANT_URL=http://your-home-assistant:8123
export HOME_ASSISTANT_TOKEN=your_long_lived_access_token
home-assistant-mcp --transport streamable-http --host 0.0.0.0 --port 8000
See Installation and Deployment for the full matrix (PyPI extras, Docker image, all transports, the agent server, reverse proxy, DNS).