Home Assistant MCP

An OAuth-protected Model Context Protocol (MCP) server for securely connecting ChatGPT, Codex, and other MCP clients to Home Assistant.

The project exposes 99 typed tools for discovery, dashboards, schedules, climate, energy, media, cleaning, irrigation, automations, diagnostics, and carefully bounded device control. It keeps Home Assistant's API private and deliberately avoids becoming a generic shell, log reader, network scanner, or unrestricted service proxy.

Highlights

• Typed Home Assistant access: entities, devices, areas, history, weather, calendars, schedules, statistics, integrations, dashboards, to-do lists, automations, backups, and system health.

• Bounded writes: climate, lights, scenes, media players, vacuums, covers, locks, sirens, notifications, dashboards, schedules, calendars, to-do items, and automations use validated inputs and narrow service allowlists.

• Sprinkler support: live controller status, zone metadata, configuration, watering history, telemetry refresh, zone or sequence starts, and idempotent stop operations.

• Energy and SolarEdge: production, module comparison, power flow, energy breakdowns, storage summaries, telemetry, alerts, and an optional Home Assistant bridge integration.

• Persistent capability sync: compares Home Assistant's current service registry with the reviewed release baseline every five minutes and reports drift without dynamically exposing new writes.

• Sanitized diagnostics: optional fixed-route, host/runtime, outage, and fixed-subnet LAN evidence with strict limits and no raw addresses, arbitrary targets, commands, or device control.

• OAuth-native remote access: authorization code flow with S256 PKCE, dynamic client registration, scoped access tokens, and MCP resource metadata.

Version 2.6.1 currently advertises 99 tools. See CHANGELOG.md for release history.

Architecture

flowchart LR
    Client[ChatGPT, Codex, or MCP client]
    Edge[HTTPS edge<br/>Cloudflare Worker, tunnel, or reverse proxy]
    MCP[Home Assistant MCP<br/>OAuth + typed tools]
    HA[Private Home Assistant API]
    Data[(OAuth, audit, and<br/>capability-sync state)]
    Collector[Optional root-owned<br/>diagnostics collector]
    Export[Sanitized read-only export]

    Client -->|HTTPS + OAuth/PKCE| Edge
    Edge -->|loopback or shared-secret origin| MCP
    MCP -->|long-lived service token| HA
    MCP --> Data
    Collector --> Export --> MCP

The reference deployment binds the MCP service to 127.0.0.1:8000. Only the HTTPS edge is public. Home Assistant can remain local to the host or reachable over a private network.

Tool surface

Higher-risk actions are annotated as destructive and require an explicit confirmation argument. The exact registry is authoritative; inspect it from an authenticated MCP client after deployment.

Requirements

• Home Assistant reachable from the MCP host.

• A dedicated Home Assistant long-lived access token. Use a separate service identity when possible.

• Python 3.12 or newer and uv for development and tests.

• Docker with Compose for the reference container deployment.

• A public HTTPS URL for remote MCP clients.

• An HTTPS edge that reaches the MCP over loopback or injects the configured origin shared secret. The included Caddy and Cloudflare examples demonstrate those two patterns.

• Linux and systemd only if using the optional host diagnostics collector.

The bundled Compose file is a production reference, not a universal one-command installer. It assumes host networking, an existing Home Assistant configuration at /opt/homeassistant/config, and an installed diagnostics export at /var/lib/ha-host-diagnostics/export. Adapt those mounts to your installation without exposing the Home Assistant API or Docker socket.

Quick start for development

Clone the repository and install the locked dependencies:

git clone https://github.com/shogun301/ha-chatgpt-mcp.git
cd ha-chatgpt-mcp
uv sync --frozen

The test suite and public-source audit do not need production credentials:

uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

To run the service, copy .env.example to an ignored .env, replace every example domain and entity ID, and provide the required runtime paths and secret files described below. The application does not automatically load .env; export the variables in your process manager, use uvicorn --env-file .env, or let Docker Compose load it.

For a local process after configuring the environment:

uv run uvicorn app.server:app --host 127.0.0.1 --port 8000 --no-proxy-headers

For the reference container deployment after adapting its mounts and optional integrations:

docker compose build --pull
docker compose up -d
curl --fail http://127.0.0.1:8000/healthz

Do not bind Uvicorn directly to a public interface.

Configuration

Core settings

Entity-specific variables in .env.example map the generic tool surface to one deployment's presence, notification, vacuum, sprinkler, thermostat, and schedule entities. Keep real entity IDs in local configuration, not in Git.

Required secret files

The server reads secrets from files rather than environment values:

Generate random values with a cryptographically secure generator. An Argon2 password hash can be produced without placing the password in shell history:

uv run python -c "from argon2 import PasswordHasher; from getpass import getpass; print(PasswordHasher().hash(getpass('OAuth password: ')))"
uv run python -c "import secrets; print(secrets.token_urlsafe(48))"

Store the outputs in separate files with owner-only permissions. Never commit secrets/, .env, tokens, passwords, hashes, private domains, entity inventories, schedules, or network topology.

Optional SolarEdge configuration

SolarEdge support uses optional client credentials, an encrypted token store, bridge secret, redirect URI, and guarded portal fallback credentials. If you do not use SolarEdge, omit the corresponding SOLAREDGE_*_FILE variables. The reference Compose file sets those paths, so either provide the files or remove those entries in your local override.

OAuth scopes

• mcp:read permits read tools.

• mcp:write permits the reviewed write surface and also satisfies the current strongest compatibility grant.

• mcp:diagnostics, together with mcp:read, permits privileged read-only host and LAN diagnostics without granting device writes.

Connect clients to https://your-mcp-host.example/mcp. The server publishes OAuth authorization-server, protected-resource, OpenID configuration, and dynamic client-registration metadata under the same origin.

Edge options

The application requires non-loopback requests to carry the configured origin shared secret. Two examples are included:

• cloudflare/ contains a narrow Cloudflare Worker proxy. It forwards only the MCP, OAuth, health, and SolarEdge callback paths, enforces a 1 MiB request limit, adds the origin secret, and strips unnecessary headers.

• Caddyfile provides a same-host HTTPS reverse proxy to the loopback MCP listener.

The included cloudflared service uses a token file and publishes metrics on loopback only. Replace all example routes and keep the MCP origin, Home Assistant API, and metrics listener off the public network.

Capability synchronization

Home Assistant integrations can add or remove services independently of this project. The server therefore polls Home Assistant's service registry every five minutes and persists a release-bound baseline in /data/ha-capability-sync.json.

get_capability_sync_status reports added or removed services and field-schema changes across restarts. The monitor is deliberately observational: it never calls a service and never turns an unreviewed Home Assistant service into a new MCP write tool. New functionality should be reviewed, implemented as typed tools, tested, and released through Git.

Optional host and LAN diagnostics

The systemd collector under collector/ has no listener and accepts no caller-selected command, path, container, log expression, or URL. It publishes bounded, sanitized snapshots and ledgers to a fixed directory. The MCP container receives only that directory as a read-only mount—never the Docker socket, host journal, procfs, sysfs, or systemd control.

The LAN tools operate only inside one configured /24, return opaque node IDs, use a closed TCP-service allowlist, send no application payload, and omit raw addresses. They cannot scan arbitrary networks or control devices.

See docs/operations.md and collector/README.md for the full data model, retention limits, deployment, verification, incident, and rollback procedures.

Security model

This server is intentionally narrower than the Home Assistant API:

• No shell execution, arbitrary WebSocket passthrough, arbitrary files, raw logs, Docker administration, service restart, shutdown, credential retrieval, camera imagery, or alarm disarming.

• Generic Home Assistant service calls are allowlisted by domain and service; dedicated typed tools are preferred.

• Inputs are schema-validated, result sizes are bounded, and sensitive diagnostic fields are recursively redacted.

• Destructive or physical operations use explicit annotations and confirmation gates.

• Audit records contain tool names and bounded metadata, not credentials or returned diagnostic evidence.

• The container runs as an unprivileged user with a read-only filesystem, all Linux capabilities dropped, and no-new-privileges enabled.

• The public-release audit scans both the current tree and Git history before publication.

Never use a thermostat, light, lock, vacuum, sprinkler, camera, speaker, television, backup, notification, or other physical side effect as a connectivity test.

For vulnerability reporting and handling of sensitive deployment information, read SECURITY.md.

Deployment and verification

The PowerShell deployment script in scripts/deploy-production.ps1 is an opinionated AWS Lightsail reference. It requires explicit AWS profile, region, instance, frontend URL, and MCP URL parameters; packages the reviewed source; creates backups; deploys the collector and container; runs verification; and supports rollback. Review it carefully before adapting it to another host.

Before every public push or production release:

uv sync --frozen
uv run python scripts/public_release_audit.py --history
uv run --with pytest python -m pytest tests collector/tests home_assistant/tests

Then verify, without changing device state:

1. /healthz succeeds locally and through the public edge.

2. Unauthenticated and invalid-token MCP requests are rejected.

3. Authenticated discovery reports the expected version and tool count.

4. Read-only overview, capability-sync, route, and integration checks succeed.

5. The public Git commit, deployed artifact, and reported service version are identical.

Production procedures and rollback gates are detailed in docs/operations.md.

Contributing

Issues and pull requests are welcome when they preserve the project's bounded security model.

For new tools:

1. Prefer a narrow typed operation over generic passthrough.

2. Define read-only, idempotent, write, or destructive annotations accurately.

3. Validate entity domains, enums, lengths, time windows, and result limits.

4. Require explicit confirmation for consequential physical or administrative actions.

5. Add authorization, negative-path, redaction, and regression tests.

6. Update capability documentation and run the public history audit.

Do not include real household configuration, private URLs, credentials, logs, tokens, schedules, topology, or provider responses in an issue, fixture, screenshot, commit, or pull request.

License

No open-source license is currently included. Public visibility does not grant permission to copy, modify, or redistribute the code. Repository owners should add an explicit license before accepting reuse or redistribution.

References

• Model Context Protocol

• OpenAI: Build an MCP server

• OpenAI: Authenticate users

• Cloudflare Tunnel monitoring

• Cloudflare Tunnel metrics