pbs-mcp
Provides tools for interacting with a Proxmox Backup Server, including datastore status, snapshot inventory, garbage collection, verification, and pruning operations via the PBS REST API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pbs-mcp show me the status of all datastores"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| read | One-call health report: storage, GC, verify coverage, freshness, failed tasks |
2 |
| read | Configured datastores + schedules |
3 |
| read | total / used / available bytes |
4 |
| read | Per-group snapshot count, owner, corruption flag |
5 |
| read | Newest-first with |
6 |
| read | UPID → running / OK / error |
7 |
| read | Paginate a task log, or |
8 |
| read | Recent tasks; full UPIDs handed out for running/failed ones |
9 |
| read | Last GC stats: bytes referenced, pending, removed |
10 |
| read | Scheduled verify jobs + re-verify policy |
11 |
| read | Preview which snapshots a retention policy would drop |
12 |
| write | Trigger GC, returns UPID (async) |
13 |
| write | Trigger verify, optional snapshot scope |
14 |
| write | Apply retention policy |
15 |
| write | Set/clear the protected flag (prune/forget skip protected) |
16 |
| write | Delete one snapshot (corrupt cleanup) |
17 |
| 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-ownerafter 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 ofconfirm.Two-key requirement on writes.
PBS_ALLOW_WRITE=trueopens the door; each call still needsconfirm=true. Two independent toggles, two intentional actions.Async tasks return UPIDs, not results.
run_gcandrun_verifykick off work and hand back a UPID immediately. Poll withget_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!mcpthe 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=falseis fine for a LAN setup. For real CAs, setPBS_VERIFY_TLS=trueandPBS_CA_BUNDLEto 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]
pytestTests stub the HTTP layer — no PBS instance needed.
License
GPL-3.0-or-later. See LICENSE.
Available Tools
17 toolspbs_datastore_statusBRead-onlyIdempotent
Total / used / available bytes for one datastore.
Inputs: params (required). Returns: result
pbs_forget_snapshotADestructive
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_statusARead-onlyIdempotent
Return the last garbage-collection statistics: bytes referenced, pending, removed, plus any flagged-bad chunks.
Inputs: params (required). Returns: result
pbs_get_task_logARead-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_statusARead-onlyIdempotent
Return current state of a PBS task (running / stopped) plus exit status if finished.
Inputs: params (required). Returns: result
pbs_health_overviewARead-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_datastoresARead-onlyIdempotent
List every configured PBS datastore with its path and any scheduled GC/prune jobs.
Inputs: params (required). Returns: result
pbs_list_groupsARead-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_snapshotsARead-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_tasksARead-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_jobsARead-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_snapshotAIdempotent
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_pruneADestructive
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_runARead-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_gcADestructive
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_taskADestructiveIdempotent
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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for managing Proxmox VE clusters — provision VMs and containers, manage snapshots and backups, execute commands, browse storage, and monitor resources through natural language37204 PyPI18MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for Proxmox VE that enables AI assistants to inspect and manage LXC containers, VMs, snapshots, and resource pools via the Proxmox API.-
- AlicenseAqualityDmaintenanceEnables LLM agents to monitor and manage a Proxmox VE cluster, including cluster status, VM/container lifecycle, and node actions via MCP tools.8MIT
- AlicenseAqualityCmaintenanceMCP 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.611 npm2AGPL 3.0