backrest-mcp

MCP server for Backrest — a web UI and orchestrator for restic backups.

Python/FastMCP rewrite of backrest-mcp-server. Covers the full useful surface of the Backrest REST API with layered safety controls to protect backup data.

Tools

Tool	Description	Requires
get_health	Check reachability + credential health (poll-safe)	—
get_config	Read Backrest configuration (repos, plans)	—
list_snapshots	List snapshots; no args → all repos merged	—
list_snapshot_files	Browse files within a snapshot (by repo_id)	—
get_summary	30-day dashboard stats per repo and plan	—
get_operations	Recent operation history with status icons + log refs	—
get_logs	Read an operation's log output (ref from get_operations)	—
get_download_url	Signed download URL for a restored file	—
trigger_backup	Trigger a backup plan (dry_run supported)	BACKREST_READONLY=false
do_repo_task	Run maintenance: prune/check/stats/unlock/index	BACKREST_READONLY=false
cancel_operation	Cancel a running operation	BACKREST_READONLY=false
forget_snapshot	Permanently forget a snapshot (confirm token required)	BACKREST_ALLOW_DESTRUCTIVE=true
restore_snapshot	Restore snapshot to a staging path	BACKREST_ALLOW_DESTRUCTIVE=true

Default state: read-only — only the 8 read tools are registered. No write calls are possible without explicit opt-in. RunCommand, SetConfig, AddRepo, RemoveRepo, and ClearHistory are intentionally never exposed.

API field names target the deployed Backrest v1.13.0 connect-rpc API, which upstream main has since diverged from. See CHANGELOG.md (0.3.0) for the reconciliation notes.

Safety Controls

Backups are critical data. Four controls gate write and destructive operations:

1. Read-only mode (default: on)

BACKREST_READONLY=true   # no write tools registered (default)
BACKREST_READONLY=false  # enables trigger_backup, do_repo_task, cancel_operation

2. Destructive gate (default: off)

BACKREST_ALLOW_DESTRUCTIVE=false  # forget/restore never registered (default)
BACKREST_ALLOW_DESTRUCTIVE=true   # enables forget_snapshot, restore_snapshot
                                   # requires BACKREST_READONLY=false

3. Forget confirmation token

forget_snapshot requires confirm=f"FORGET:{snapshot_id}". The caller must name the exact snapshot being deleted.

4. Restore path guard

restore_snapshot validates the target path against BACKREST_RESTORE_ALLOWED_PREFIX (default: /tmp/backrest-restore/) using os.path.realpath(). Path traversal attempts are blocked. After verifying restored files, move them manually.

5. Audit log

Set BACKREST_AUDIT_LOG=/path/to/audit.jsonl to log all write operations. Credential values are never included.

Configuration

Env var	Default	Purpose
BACKREST_URL	http://localhost:9898	Backrest base URL
BACKREST_USERNAME	—	Basic Auth username (optional)
BACKREST_PASSWORD	—	Basic Auth password
BACKREST_READONLY	true	Disable all write tools
BACKREST_ALLOW_DESTRUCTIVE	false	Enable forget/restore (requires READONLY=false)
BACKREST_RESTORE_ALLOWED_PREFIX	/tmp/backrest-restore/	Restore target path guard
BACKREST_AUDIT_LOG	—	JSONL audit log for write ops
BACKREST_MCP_TRANSPORT	stdio	stdio or http (long-lived PM2 service)
BACKREST_MCP_HTTP_HOST	127.0.0.1	Bind host for http mode (non-loopback refused)
BACKREST_MCP_HTTP_PORT	8626	Bind port for http mode
BACKREST_MCP_AUTH_TOKEN	—	Bearer token, required in http mode (≥16 chars)
LOG_LEVEL	INFO	Logging verbosity
LOG_FILE	stderr	Log file path
INFLUXDB_URL	—	Optional InfluxDB metrics

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

For development/testing:

pip install -e ".[dev]"
pytest

Deployment (PM2)

An ecosystem.config.js is included for PM2-managed deployment. Credentials are injected via --env-file to avoid storing them in the config file:

cd /path/to/backrest-mcp
pm2 start ecosystem.config.js --env-file /path/to/secrets.env

The secrets file must contain BACKREST_USERNAME, BACKREST_PASSWORD, and (for http mode) BACKREST_MCP_AUTH_TOKEN. All other settings default safely in ecosystem.config.js (BACKREST_READONLY=true, BACKREST_ALLOW_DESTRUCTIVE=false).

HTTP transport

ecosystem.config.js defaults to BACKREST_MCP_TRANSPORT=http, running a long-lived streamable-http service on 127.0.0.1:8626/mcp. HTTP mode fails closed:

• binds loopback only (non-loopback bind refused unless BACKREST_MCP_ALLOW_NONLOOPBACK=1);
• requires a BACKREST_MCP_AUTH_TOKEN bearer token of ≥16 chars (generate with python3 -c "import secrets; print(secrets.token_hex(32))").

Clients authenticate with Authorization: Bearer <token>. Set BACKREST_MCP_TRANSPORT=stdio (or unset it) to fall back to per-turn stdio via the backrest-mcp entry point.

Claude Desktop Config

{
  "mcpServers": {
    "backrest": {
      "command": "/path/to/backrest-mcp/.venv/bin/python",
      "args": ["-m", "backrest_mcp.server"],
      "env": {
        "BACKREST_URL": "http://localhost:9898",
        "BACKREST_USERNAME": "your-username",
        "BACKREST_PASSWORD": "your-password",
        "BACKREST_READONLY": "true"
      }
    }
  }
}

Omit BACKREST_USERNAME and BACKREST_PASSWORD if Backrest auth is disabled.

TLS

If connecting to an HTTPS endpoint with a private or self-signed CA:

REQUESTS_CA_BUNDLE=/path/to/ca.crt

httpx respects this env var. Do not disable TLS verification.

Observability

Structured JSON logs via structlog. LOG_LEVEL controls verbosity (default: INFO). Set LOG_FILE to write to a file instead of stderr — exactly one sink is attached, so under PM2 the same line is not also duplicated into error_file. If LOG_FILE cannot be created the server falls back to stderr and says so on stderr rather than failing to start.

LOG_LEVEL applies to this server's own loggers. httpx, httpcore, mcp and nats are held at WARNING regardless, so their wire trace cannot drown the server's own lines.

Optional InfluxDB metrics via pip install -e ".[influxdb]":

Env var	Purpose
INFLUXDB_URL	InfluxDB write URL
INFLUXDB_TOKEN	Auth token
INFLUXDB_BUCKET	Bucket/database (default: backrest-mcp)

Optional NATS publishing via pip install -e ".[nats]":

Env var	Purpose
NATS_URL	NATS server URL. Unset = disabled.
NATS_SUBJECT_PREFIX	Subject prefix (default: backrest); subjects are <prefix>.tool.<tool>

Each tool call emits a backrest_tool measurement with tool tag and duration_ms field.

Failure behaviour

Telemetry is best-effort and never fails a tool call, but it is not silent. An unset env var is the intended disabled state and logs nothing. A backend that is configured and failing warns exactly once per process and is then not retried:

Event	Meaning
influx_init_failed	INFLUXDB_URL set but the client could not be built. Writes disabled for the process.
influx_write_failed	The client built but a write failed — the usual symptom of a wrong or unreachable URL, since InfluxDBClient3 connects lazily. Writes keep being attempted.
nats_init_failed	NATS_URL set but the connection failed. Publishes disabled for the process.
nats_transport_error	First NATS transport error, in place of nats-py's per-attempt ERROR reporting.
nats_publish_failed	The connection succeeded but a publish failed. Publishes keep being attempted.

Every one of these carries the exception class only, never the URL or token — a NATS URL embeds its credentials.

NATS connects fail fast (allow_reconnect=False, two attempts, 2 s connect timeout, 5 s overall deadline) so an unreachable broker delays a tool call by well under a second rather than the ~120 s the library defaults produce.

Auth Architecture

Credentials flow: env vars → BackrestClient.__init__ → httpx Basic Auth tuple → Authorization header. Credentials are never written to logs, audit entries, or MCP tool responses.