homeassistant-ai/ha-mcp

📚 What is ha‑mcp?

ha‑mcp (Home Assistant Model Context Protocol server) is an unofficial but fully‑featured server that lets large‑language‑model assistants (Claude, ChatGPT, Gemini, etc.) talk to a Home Assistant instance. It implements the Model Context Protocol (MCP) so an AI client can:

Query the state of any entity (lights, sensors, cameras, …).
Control devices via any Home Assistant service.
Create, edit, and debug automations, scripts, dashboards, helpers, zones, groups, blue‑prints, HACS add‑ons, backups, and more.
Read logs, history, and automation traces to help the AI troubleshoot problems.
Toggle safety features (read‑only mode, per‑tool permissions, automatic edit backups) so you can keep control over what the assistant may change.

In short, it turns a conversational AI into a full‑blown Home Assistant admin that can build and maintain your smart‑home configuration, not just turn lights on and off.

🚀 How do you run it?

ha‑mcp can be installed in four ways, all of which expose a single URL that your AI client points to:

Method	Where it runs	Typical use‑case
HA‑MCP Custom Component (recommended)	Inside Home Assistant as a custom integration (installed via HACS)	Works on every Home Assistant installation type (OS, Supervised, Container, Core). No extra tokens needed.
Home Assistant app / add‑on	As a separate “app” on Home Assistant OS / Supervised	Good if you prefer a stand‑alone process but still want the built‑in webhook for remote access.
Docker / PyPI / uvx HTTP server	Outside Home Assistant (any host)	Useful for Container or Core installs that cannot run add‑ons, or if you want to host the server on a different machine.
Local stdio	Directly on your laptop/desktop (not recommended for production)	Quick demo or tinkering; suffers from known transport glitches.

All methods generate a secret webhook URL (or a direct local port) that you paste into the AI client’s MCP configuration.

🔧 Quick‑start (Custom Component)

Add the integration via HACS – use the badge in the README or add the repo https://github.com/homeassistant-ai/ha-mcp-integration as a custom repository.
Restart Home Assistant.
In Settings → Devices & Services → Add Integration, search for HA‑MCP Custom Component and add the HA‑MCP Server entry.
After the server starts, open its Configure screen; the webhook URL (e.g. https://my‑ha.duckdns.org/api/webhook/abcd1234) is shown and also appears in the Home Assistant log.
Paste that URL into your AI client’s MCP settings – the assistant can now talk to Home Assistant.

The integration also adds a sidebar panel for managing tools, feature flags, backups, and themes, and lets you enable optional webhook authentication (ha_auth).

🛠️ What can the AI actually do?

ha‑mcp ships 87 “tools” grouped by function. Some of the most common actions demonstrated in the README are:

Category	Example tools
Control	`ha_call_service`, `ha_bulk_control` – turn devices on/off, adjust climate, etc.
Automation & Scripts	`ha_config_get_automation`, `ha_config_set_automation`, `ha_config_get_script`, `ha_config_set_script` – create or modify automations and scripts.
Dashboard / UI	`ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_get_dashboard_screenshot` – add cards, edit Lovelace layouts.
File & YAML (beta)	`ha_read_file`, `ha_write_file`, `ha_config_get_yaml`, `ha_config_set_yaml` – edit raw configuration files.
System & Maintenance	`ha_manage_backup`, `ha_manage_updates`, `ha_restart`, `ha_reload_core` – backup/restore, update Home Assistant, restart services.
Debug & Monitoring	`ha_get_history`, `ha_get_logs`, `ha_get_automation_traces` – fetch logs, view entity history, debug failing automations.
Safety	`ha_manage_security_policy`, `Read Only Mode toggle` – restrict what the AI may change.

When you ask the assistant something like “Create an automation that turns on the porch light at sunset”, it calls the appropriate ha_config_set_automation tool behind the scenes, writes the YAML, and reloads the config.

🌐 Remote access options

Built‑in webhook (used by the custom component) – works with Nabu Casa, Cloudflare Tunnel, or any reverse proxy.
Webhook Proxy app – for the add‑on method, forwards MCP traffic through an existing Home Assistant webhook.
OpenAI Tunnel – community‑maintained tunnel that lets ChatGPT‑style connectors reach a locally‑hosted server without exposing a public URL.
OIDC authentication – optional mode to protect the webhook behind an external identity provider (Keycloak, Auth0, etc.).

📦 Demo & Setup Wizard

The repo provides one‑command demo scripts for macOS, Linux, and Windows that spin up a temporary stdio‑based server connected to a hosted demo Home Assistant. After running the script you can ask Claude, ChatGPT, or any MCP‑compatible client “Can you see my Home Assistant?” to see the integration in action.

A web‑based Setup Wizard (https://homeassistant-ai.github.io/ha-mcp/setup/) generates the exact client‑specific configuration for all supported clients (Claude Code, Gemini CLI, ChatGPT, VS Code, Cursor, etc.).

🆚 How does it differ from Home Assistant’s built‑in MCP Server?

Feature	Built‑in MCP Server	ha‑mcp
Device control & state query	✅ (only entities exposed to Assist)	✅ (all entities)
Edit automations, scripts, scenes	❌	✅
Edit dashboards / Lovelace UI	❌	✅
Access logs, history, automation traces	❌	✅
Manage helpers, areas, zones, groups, labels	❌	✅
Backup/restore, app management, HACS, device registry	❌	✅

Use the built‑in server for simple voice‑style commands; use ha‑mcp when you want the AI to configure and maintain your whole Home Assistant setup.

📚 Where to learn more?

Documentation site – https://homeassistant-ai.github.io/ha-mcp/
Setup Wizard – https://homeassistant-ai.github.io/ha-mcp/setup/
FAQ & Troubleshooting – https://homeassistant-ai.github.io/ha-mcp/faq/
GitHub repo – https://github.com/homeassistant-ai/ha-mcp (issues, contribution guide, release notes)

TL;DR

ha‑mcp is a real, production‑ready server that bridges large‑language‑model assistants to Home Assistant, giving the AI full read/write access to the entire Home Assistant configuration. Install it via the HA‑MCP custom component (the easiest path), grab the generated webhook URL, and point any MCP‑compatible AI client at it – then you can ask your AI to create automations, edit dashboards, debug problems, and more, all through natural language.