Skip to main content
Glama
pbs-mcp
by ahmetem

pbs-mcp

MCP server for Proxmox Backup Server. Exposes datastore status, snapshot inventory, garbage collection, verify, and prune over the PBS REST API as 17 LLM-callable tools. Designed for the Model Context Protocol.

Türkçe için → README.tr.md

Why

PBS already has a polished web UI. This server is for the cases where the UI isn't where you are — answering "is anything broken?" from a chat assistant, or wiring PBS state into a homelab agent that schedules verifies and prunes based on real conditions.

Related MCP server: proxmox-mcp

Tools (17)

#

Tool

Mode

Notes

1

pbs_health_overview

read

One-call health report: storage, GC, verify coverage, freshness, failed tasks

2

pbs_list_datastores

read

Configured datastores + schedules

3

pbs_datastore_status

read

total / used / available bytes

4

pbs_list_groups

read

Per-group snapshot count, owner, corruption flag

5

pbs_list_snapshots

read

Newest-first with limit; summary=true for one row per group

6

pbs_get_task_status

read

UPID → running / OK / error

7

pbs_get_task_log

read

Paginate a task log, or tail=true for just the end

8

pbs_list_tasks

read

Recent tasks; full UPIDs handed out for running/failed ones

9

pbs_gc_status

read

Last GC stats: bytes referenced, pending, removed

10

pbs_list_verify_jobs

read

Scheduled verify jobs + re-verify policy

11

pbs_prune_dry_run

read

Preview which snapshots a retention policy would drop

12

pbs_run_gc

write

Trigger GC, returns UPID (async)

13

pbs_run_verify

write

Trigger verify, optional snapshot scope

14

pbs_prune

write

Apply retention policy

15

pbs_protect_snapshot

write

Set/clear the protected flag (prune/forget skip protected)

16

pbs_forget_snapshot

write

Delete one snapshot (corrupt cleanup)

17

pbs_stop_task

write

Abort a running task (e.g. GC stuck on slow NFS)

Start with pbs_health_overview for any "is PBS okay?" question — it fetches datastore status, GC stats, groups, snapshots, node status, and recent tasks concurrently and condenses them into one verdict, replacing five separate tool calls.

Write tools require both PBS_ALLOW_WRITE=true in the environment and confirm=true in the call itself. Restore is intentionally out of scope — the standard proxmox-mcp already handles restore from PBS via archive= on the Proxmox VE side.

Setup

1. Create an API token in PBS

In a shell on the PBS host (pct enter 205 from Proxmox if PBS lives in an LXC, otherwise just SSH):

# Generate a token under root@pam
proxmox-backup-manager user generate-token root@pam mcp

# Grant it admin on your datastore
proxmox-backup-manager acl update /datastore/<your-datastore> \
  DatastoreAdmin --auth-id 'root@pam!mcp'

The generate-token output includes a value field — that's the secret, shown only once. Save it.

Why DatastoreAdmin? PBS performs an owner check on prune. Either you give the token DatastoreAdmin (this), or you keep moving backup ownership with change-owner after every push. Admin scope is simpler and stays inside one datastore.

2. Configure the MCP server

git clone https://github.com/ahmetem/pbs-mcp.git
cd pbs-mcp
cp .env.example .env
# Edit .env: fill in PBS_HOST, PBS_TOKEN_ID, PBS_TOKEN_SECRET
pip install -e .

3. Register with your MCP client

For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "pbs": {
      "command": "python",
      "args": ["/absolute/path/to/pbs-mcp/pbs_mcp.py"]
    }
  }
}

Restart the client. The pbs_* tools should appear.

Safety model

  • Read-only by default. Out of the box PBS_ALLOW_WRITE=false, so every state-changing tool refuses regardless of confirm.

  • Two-key requirement on writes. PBS_ALLOW_WRITE=true opens the door; each call still needs confirm=true. Two independent toggles, two intentional actions.

  • Async tasks return UPIDs, not results. run_gc and run_verify kick off work and hand back a UPID immediately. Poll with get_task_status. This prevents the MCP request from blocking for hours.

  • Token scoped to one datastore. ACLs live at /datastore/<name>, not at /. A leaked token can't read PBS user lists or remote sync configs.

Notes / gotchas

  • First-call cache lag: PBS caches ACLs for a few seconds. GET requests retry once automatically after a short delay on 403 / connect errors, so a freshly granted token usually just works. If it still fails, wait a few seconds and retry.

  • Token vs user permissions: PBS API tokens get the intersection of the parent user's ACLs and the token's ACLs. With root@pam!mcp the parent is unrestricted, so only the token's ACL matters in practice.

  • Self-signed cert: PBS ships with a self-signed cert. The default PBS_VERIFY_TLS=false is fine for a LAN setup. For real CAs, set PBS_VERIFY_TLS=true and PBS_CA_BUNDLE to a PEM file.

  • UPIDs are tied to their creator: a UPID created by a now-deleted user becomes unreadable. Don't recycle PBS users while there are pending tasks.

Development

pip install -e .[dev]
pytest

Tests stub the HTTP layer — no PBS instance needed.

License

GPL-3.0-or-later. See LICENSE.

Available Tools

17 tools
pbs_datastore_statusB
Read-onlyIdempotent

Total / used / available bytes for one datastore.

Inputs: params (required). Returns: result

pbs_forget_snapshotA
Destructive

Permanently delete one snapshot. The on-disk chunks are freed by the next garbage collection. Requires PBS_ALLOW_WRITE=true and confirm=true.

Inputs: params (required). Returns: result

pbs_gc_statusA
Read-onlyIdempotent

Return the last garbage-collection statistics: bytes referenced, pending, removed, plus any flagged-bad chunks.

Inputs: params (required). Returns: result

pbs_get_task_logA
Read-onlyIdempotent

Fetch log lines from a PBS task. Supports pagination via start/limit, or tail=true for just the end of the log — usually all you need to see how a verify or GC finished.

Inputs: params (required). Returns: result

pbs_get_task_statusA
Read-onlyIdempotent

Return current state of a PBS task (running / stopped) plus exit status if finished.

Inputs: params (required). Returns: result

pbs_health_overviewA
Read-onlyIdempotent

One-call health report for a datastore: storage usage, node load, last GC result, snapshot/verify coverage, backup freshness, corrupt groups, and failed/running tasks. Start here for any 'is PBS okay?' question — it replaces separate status/gc/tasks/groups calls.

Inputs: params (required). Returns: result

pbs_list_datastoresA
Read-onlyIdempotent

List every configured PBS datastore with its path and any scheduled GC/prune jobs.

Inputs: params (required). Returns: result

pbs_list_groupsA
Read-onlyIdempotent

List every backup group on a datastore with its snapshot count, last-backup time, owner, and file count. Groups with zero files are flagged as likely corrupt.

Inputs: params (required). Returns: result

pbs_list_snapshotsA
Read-onlyIdempotent

List snapshots on a datastore with size, file count, protected flag, and last verify state — newest first, capped at limit. Set summary=true for one aggregate row per group instead (preferred for overviews).

Inputs: params (required). Returns: result

pbs_list_tasksA
Read-onlyIdempotent

Browse recent PBS tasks with optional type filter, running-only flag, and errors-only flag. Running or failed tasks come with their full UPID for follow-up via pbs_get_task_status / pbs_get_task_log.

Inputs: params (required). Returns: result

pbs_list_verify_jobsA
Read-onlyIdempotent

List configured verify jobs: schedule, datastore, and re-verify policy. Answers 'is verification scheduled at all?' — pbs_list_datastores only shows GC/prune schedules.

Inputs: params (required). Returns: result

pbs_protect_snapshotA
Idempotent

Set or clear the protected flag on one snapshot. Protected snapshots are skipped by prune and cannot be forgotten until unprotected. Requires PBS_ALLOW_WRITE=true and confirm=true.

Inputs: params (required). Returns: result

pbs_pruneA
Destructive

Apply a retention policy and drop matching snapshots. The on-disk chunks aren't freed until the next garbage collection. Always run pbs_prune_dry_run first. Requires PBS_ALLOW_WRITE=true and confirm=true.

Inputs: params (required). Returns: result

pbs_prune_dry_runA
Read-onlyIdempotent

Preview which snapshots in a backup group would be kept or dropped by a given retention policy.

Inputs: params (required). Returns: result

pbs_run_gcA
Destructive

Trigger a garbage-collection run. GC walks every chunk and frees those no longer referenced by any snapshot. Async — returns a UPID immediately. Requires PBS_ALLOW_WRITE=true and confirm=true.

Inputs: params (required). Returns: result

pbs_run_verifyA

Trigger a verify task. Verify re-reads every chunk and confirms it matches its expected hash, catching bitrot. By default skips snapshots that were verified OK in the past 30 days. Async — returns a UPID. Requires PBS_ALLOW_WRITE=true and confirm=true.

Inputs: params (required). Returns: result

pbs_stop_taskA
DestructiveIdempotent

Abort a running PBS task (e.g. a GC or verify stuck on a slow NFS datastore). The task stops at the next safe point; an interrupted GC or verify can simply be re-run later. Requires PBS_ALLOW_WRITE=true and confirm=true.

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a distinct target: task status/log/list/stop, GC run/status, datastore list/status, snapshot list/protect/forget, verify list/run, prune dry-run/apply, and health overview. No two tools overlap in purpose.

    Naming Consistency4/5

    The pbs_ prefix is consistent and most tools follow verb_noun (list_datastores, run_verify, protect_snapshot). A few deviations exist (pbs_datastore_status, pbs_gc_status, pbs_health_overview) but they remain clear and readable.

    Tool Count5/5

    17 tools covers the main PBS domains (datastores, snapshots, tasks, GC, verify, prune, health) without redundancy or bloat. Each tool serves a real administrative need.

    Completeness4/5

    The set thoroughly covers monitoring and maintenance operations, including dry-run for prune and a health overview. It lacks datastore/group creation/deletion, but those are arguably out of scope for an admin tool, and the core lifecycle of snapshots (list, protect, forget) is present.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for managing Proxmox VE clusters — provision VMs and containers, manage snapshots and backups, execute commands, browse storage, and monitor resources through natural language
      37
      204 PyPI
      18
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Proxmox VE that enables AI assistants to inspect and manage LXC containers, VMs, snapshots, and resource pools via the Proxmox API.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables LLM agents to monitor and manage a Proxmox VE cluster, including cluster status, VM/container lifecycle, and node actions via MCP tools.
      8
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Proxmox VE and Proxmox Datacenter Manager, covering every API endpoint via six consolidated tools for list, describe, and call operations with a read-only safety gate.
      6
      11 npm
      2
      AGPL 3.0