Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Remote

Manage Backups

ha_manage_backup
Destructive

Manage Home Assistant backups: create, list, restore, and delete full snapshots or per-edit auto-backups, and diff or view backup contents.

Instructions

Manage Home Assistant backups — both full HA snapshots AND per-edit auto-backups.

Pick the scope first, then the action. Wrong scope routes through the wrong code path:

scope

action

What it does

snapshot

create

Create a full HA tarball (config + addons, no DB by default). Can take a while on a large instance; progress heartbeats are sent while waiting.

snapshot

list

List full HA tarball snapshots (id, name, date, size). Read-only — use to discover a backup_id or confirm a backup landed.

snapshot

restore

Restore a full HA tarball. Restarts HA. Last-resort recovery.

snapshot

delete

Delete one full HA tarball by backup_id (confirm=True required). Disabled by default (enable_snapshot_delete setting) and layered with guards even when enabled — see below.

edits

create

On-demand snapshot of one entity (domain + entity_id required). Use before the user manually edits in the HA UI. Same handler path the decorator takes on writes; bypasses the enable_auto_backup toggle.

edits

list

List per-entity auto-backups (lightweight). Filter by domain and/or entity_id.

edits

view

Read one auto-backup file by name; returns YAML and parsed config.

edits

diff

Compare one auto-backup against the entity's current config. RFC 6902 JSON-Patch + add/remove/replace counts; bounded output. Read-only — fetches the live config, makes no changes.

edits

restore

Re-apply one auto-backup. Creates a fresh safety snapshot first. No HA restart.

edits

delete

Delete one auto-backup by backup_name, or bulk-delete by filter.

When to use which scope:

  • Use scope="edits" to undo a recent automation/script/scene/dashboard/helper edit by the agent. Lightweight, fast, no restart.

  • Use scope="snapshot" only for system-wide recovery (botched add-on update, mass config corruption, etc.).

scope="snapshot" backup-hint: Run before operations that CANNOT be undone (e.g., deleting devices). If the current definition was fetched or can be fetched, this tool is usually not needed.

(snapshot, delete) is off by default and layered even when enabled: a human must set enable_snapshot_delete=true (env var, web settings UI, or add-on Supervisor options) — an agent cannot turn this on itself. When enabled, a delete call is still refused if: the target is a scheduled/automatic backup; it's younger than snapshot_delete_min_age_days (default 7, 0 disables the floor); or it's the single newest snapshot remaining. These guarantee at least one recovery point always survives an agent's own mistakes.

enable_auto_backup and scope="edits": the automatic-on-write capture (every wrapped tool call) is gated by enable_auto_backup=true — if the listing is empty, check the toggle (web settings UI or ENABLE_AUTO_BACKUP=true env var). The explicit (edits, create) action bypasses the toggle since the request is explicit; list / view / restore / delete operate on whatever's already on disk regardless of the toggle's current state.

Examples:

  • Snapshot before risky op: ha_manage_backup(scope="snapshot", action="create", name="Before_Big_Change")

  • List snapshots (to discover a backup_id or confirm one landed): ha_manage_backup(scope="snapshot", action="list")

  • Restore full snapshot: ha_manage_backup(scope="snapshot", action="restore", backup_id="dd7550ed")

  • Delete an old snapshot (requires enable_snapshot_delete=true): ha_manage_backup(scope="snapshot", action="delete", backup_id="dd7550ed", confirm=True)

  • On-demand entity snapshot before a manual UI edit: ha_manage_backup(scope="edits", action="create", domain="helper_input_boolean", entity_id="kitchen_lights_active")

  • List recent auto-backups for one automation: ha_manage_backup(scope="edits", action="list", domain="automation", entity_id="kitchen_lights")

  • View an auto-backup: ha_manage_backup(scope="edits", action="view", backup_name="automation.kitchen_lights.20260521_153000.yaml")

  • Diff an auto-backup vs current state: ha_manage_backup(scope="edits", action="diff", backup_name="automation.kitchen_lights.20260521_153000.yaml")

  • Restore an auto-backup: ha_manage_backup(scope="edits", action="restore", backup_name="automation.kitchen_lights.20260521_153000.yaml")

  • Delete one auto-backup: ha_manage_backup(scope="edits", action="delete", backup_name="...")

  • Bulk-delete old auto-backups: ha_manage_backup(scope="edits", action="delete", older_than_days=30)

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNo(snapshot.create) Tarball name. Auto-generated if not provided.
limitNo(edits.list / snapshot.list) Maximum number of entries to return.
scopeYes'snapshot' for full HA tarballs; 'edits' for per-entity auto-backups.
actionYesOperation to perform. Valid (scope, action) combinations are listed in the tool description.
domainNo(edits.create / edits.list / edits.delete) Filter auto-backups by domain (e.g. 'automation', 'helper_timer'). Required for edits.create.
confirmNo(snapshot.delete) Must be True to confirm deletion — a safety measure against accidental calls.
backup_idNo(snapshot.restore / snapshot.delete) Tarball ID (e.g. 'dd7550ed').
entity_idNo(edits.create / edits.list / edits.delete) Filter auto-backups by entity ID. Required for edits.create.
backup_nameNo(edits.view / edits.restore / edits.delete) Auto-backup filename (format '<domain>.<entity_id>.<timestamp>.yaml'). Not a tarball ID.
older_than_daysNo(edits.delete) Bulk-delete auto-backups older than this many days.
restore_databaseNo(snapshot.restore) Include database in the restore. Default false (config-only).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed2 schema fields changedv8.4.1
    • changedInput schema / properties / domain / description
      Previous value: -"(edits.list / edits.delete) Filter auto-backups by domain (e.g. 'automation', 'helper_timer')."New value: +"(edits.create / edits.list / edits.delete) Filter auto-backups by domain (e.g. 'automation', 'helper_timer'). Required for edits.create."
    • changedInput schema / properties / entity_id / description
      Previous value: -"(edits.list / edits.delete) Filter auto-backups by entity ID."New value: +"(edits.create / edits.list / edits.delete) Filter auto-backups by entity ID. Required for edits.create."
  2. First observedv7.14.2

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

This is exemplary transparency. It discloses that snapshot restore restarts HA, snapshot delete is disabled by default and layered with guards (age floor, not delete newest, no scheduled backups), edits restore creates a safety snapshot first and does not restart HA, list/diff are read-only, and create sends progress heartbeats. This goes far beyond the destructiveHint annotation and aligns with it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but the tool is genuinely complex: two scopes × six actions with different parameter sets and safety guards. The table, section headers, and example list make the length navigable and front-loaded. No filler or redundant prose; each section earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 11 parameters, two scopes, six actions, destructive operations, and configuration toggles, the description covers everything an agent needs: valid combinations, safety locks, operational side effects, when to use alternatives, and concrete invocation examples. The output schema exists, so return-value documentation is not required here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 100%, the description adds substantial semantic value: backup_name format, backup_id example, confirm requirement for snapshot.delete, older_than_days bulk deletion, restore_database default false, and domain/entity_id requirements for edits.create. The examples map parameter combinations to concrete calls, eliminating ambiguity about which params apply to which scope/action.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Manage Home Assistant backups — both full HA snapshots AND per-edit auto-backups.' The scope/action table enumerates every supported combination, so an agent immediately understands what the tool does and how it differs from sibling tools like ha_manage_app or ha_manage_updates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description has an explicit 'When to use which scope' section, telling the agent to use scope='edits' for undoing recent edits and scope='snapshot' only for system-wide recovery. It also warns when the tool is NOT needed ('If the current definition was fetched or can be fetched, this tool is usually not needed'), plus safety preconditions such as enable_snapshot_delete and confirm=True.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/homeassistant-ai/ha-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server