Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Manage Backups

ha_manage_backup
Destructive

Create, restore, and delete Home Assistant backups—both full system snapshots and per-entity auto-backups—to recover from config errors or revert edits without restarting.

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.list / edits.delete) Filter auto-backups by domain (e.g. 'automation', 'helper_timer').
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.list / edits.delete) Filter auto-backups by entity ID.
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

Tool Definition Quality

A5/5.0
Behavior5/5

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

Discloses that snapshot restore restarts HA, snapshot delete is disabled by default with multiple safety layers (minimum age, not newest, not scheduled), progress heartbeats during large creation, and that edits restore creates a safety snapshot first. Adds extensive detail beyond the destructiveHint annotation.

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?

Despite length, the description is well-structured with a clear summary, table mapping scope+action to behavior, usage guidelines, special case notes, and examples. Every sentence adds value and is efficiently front-loaded.

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?

Covers all (scope, action) combinations, safety guards, toggle behaviors, parameter usage, and provides comprehensive examples. With an output schema present, it does not need to explain return values.

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?

The description adds significant meaning beyond the 100% schema coverage, explaining parameter formats (e.g., backup_name format '<domain>.<entity_id>.<timestamp>.yaml'), the role of confirm, filtering by domain/entity_id, bulk-delete behavior of older_than_days, and the restore_database option.

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 clearly states it manages both full HA snapshots and per-edit auto-backups, distinguishing two scopes with specific actions. It differentiates from sibling tools (e.g., ha_config_set_automation) by focusing exclusively on backup operations.

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?

Dedicated 'When to use which scope' section explicitly advises using 'edits' for undoing agent edits and 'snapshot' for system-wide recovery, and notes when the tool is not needed. Provides explicit guidance on when to use each action.

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