Skip to main content
Glama
MCP Server for Home Assistant (HTTP Transport)

MCP Server for Home Assistant (HTTP Transport)

by ganhammar
README.md
# MCP Server for Home Assistant

Let an AI assistant such as Claude work with your Home Assistant: read what is going on, explain why something happened, and change automations, dashboards and devices for you. It is a custom integration that gives the assistant a set of tools for your Home Assistant, and it works wherever Home Assistant is reachable, including Claude on the web.

![Demo: Home Assistant is added to an assistant as a custom connector, Home Assistant's consent screen asks what the assistant, here a made-up one called Wren, may do and Look only is approved, and the question "Describe my home" is answered with the rooms on each floor, the lights that are on, the temperatures and an open balcony door, read through tools such as list_areas and search_entities. The assistant is illustrated; the Home Assistant screens and the data are real.](https://raw.githubusercontent.com/ganhammar/hass-mcp-server/main/docs/images/demo.gif)

Things you can ask once it is connected:

- "Are any lights still on upstairs?"
- "Why didn't the hallway automation run last night?"
- "Which automations and dashboards still use `light.kitchen`? I want to rename it."
- "Add a card for the new heat pump to the energy view."
- "Is anything wrong with my system right now?"
- "Create a scene for movie night and an automation that starts it when the TV turns on."

## Why this one

- **It administers the whole instance**, not only the entities exposed to Assist as Home Assistant's built-in MCP Server does: 117 tools for automations, dashboards, the registries, integrations, traces and diagnostics. See [how the two differ](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/faq.md#how-is-this-different-from-home-assistants-built-in-mcp-server).
- **Everyone signs in as themselves.** Clients authenticate through Home Assistant as a real user, with OAuth or a long-lived access token, so there is no shared secret URL and every change is logged with who made it.
- **You decide how far it reaches.** When an app connects, you choose what it may do, from Look only to Administer or area by area. On top of that come read-only mode, a switch for every tool, and opt-ins for the groups that reach furthest. A tool that is off is not even shown to the client.
- **It is tested on each change** against Home Assistant 2025.6, the oldest supported version, and three newer releases up to 2026.10.

## Quick start

**You need:** Home Assistant 2025.6 or newer, HACS, an administrator account and, for Claude on the web, an HTTPS address for Home Assistant that can be reached from the internet.

1. **Install.** In HACS, download "MCP Server" and "OIDC Provider", then restart Home Assistant. The OIDC Provider handles the sign-in for Claude; skip it if you will only use long-lived access tokens.
2. **Add the integrations.** Under Settings > Devices & Services > Add Integration, add "OIDC Provider" first, then "MCP Server (HTTP Transport)".
3. **Connect Claude.** In Claude, open Customize > Connectors > Add custom connector and enter `https://your-home-assistant/api/mcp_http`. Claude sends you to Home Assistant to sign in, choose what Claude may do, and approve.

Choose Look only, or start in read-only mode, if you want to see what it does before letting it change anything. [Connecting a client](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/connecting.md) covers other clients and long-lived access tokens.

## What it can do

| Area | Examples |
|---|---|
| Entities and state | Read and search entities, call any service, history, logbook and long-term statistics |
| Automations, scripts and scenes | List, create, update and delete them, and search their config for a reference |
| Traces | See step by step why an automation or script ran, did not run, or took the wrong branch |
| Dashboards | Read an outline, change a single card with a patch, or create and remove whole dashboards |
| Helpers | Create and manage toggles, counters, timers, schedules and the other helper types |
| Areas, floors, devices and labels | Organize the instance: create areas and floors, move and rename devices, label things |
| Integrations (opt-in) | Add an integration, change its options, reload, disable or remove it |
| Diagnostics | System status, repair issues, system health, the list of backups, the error log, config validation |
| Config files (opt-in) | Read and edit YAML files, with a snapshot of the top-level files before every change |
| Cameras and images (opt-in) | Capture a camera frame or read a saved image for the assistant to look at |
| KNX | Manage KNX entities and read recent telegrams, when KNX is set up |

The [full reference](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/tools.md) lists every tool, resource and prompt. A few tools rely on Home Assistant internals and can break on an update; they are marked there.

## Staying in control

- **Access per app.** The consent screen asks what each app may do: Look only, Control devices, Edit the setup or Administer, or None, Read or Full per area. It needs OIDC Provider 1.9.0 or newer. A connection from before keeps Administer until you change it with Change access under Connected applications, and in read-only mode it is held at Read.
- **Read-only mode** offers only the tools that read, to every connection. Nothing can be changed.
- **Disabled tools** switches off individual tools, such as `restart_ha`.
- **Opt-in groups** stay off until you enable them: config files, cameras and images, templates, AppDaemon apps and integration management.
- **The audit log and event** record who called what, with secrets masked.
- **Only administrators can connect**, unless you decide otherwise.

See [Configuration](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/configuration.md) and [Security and auditing](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/security.md).

## Documentation

- [Connecting a client](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/connecting.md): Claude on the web, long-lived access tokens
- [Configuration](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/configuration.md): every option, limiting the tools, the opt-in groups
- [Security and auditing](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/security.md): who may connect, what each app may do, the audit log and event
- [Tools, resources and prompts](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/tools.md): the full reference
- [FAQ](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/faq.md): what it is, what it can do, and staying safe
- [Troubleshooting](https://github.com/ganhammar/hass-mcp-server/blob/main/docs/troubleshooting.md): setup problems, path conflicts, IP bans

**Updating and removing.** HACS shows updates as they are released. To remove it, delete the integration under Settings > Devices & Services, remove it in HACS, restart, and remove the connector in your client.

**Help.** Questions and bugs go to the [issue tracker](https://github.com/ganhammar/hass-mcp-server/issues).

## License

[MIT](https://github.com/ganhammar/hass-mcp-server/blob/main/LICENSE)