How do I use pbs-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pbs-mcp-server what datastores do I have?" 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-server

Q: Which integrations are available for this server?

Manage Proxmox Backup Server datastores, snapshots, verification, prune jobs, sync jobs, garbage collection, and system tasks via the PBS API.

by szoran53

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

pbs-mcp-server

MCP server for Proxmox Backup Server — manage datastores, snapshots, verification, prune jobs, sync jobs, garbage collection, and more via any MCP-compatible AI client.

Tools

Node & System

Tool	Description
`pbs_get_version`	Get PBS version and repo ID
`pbs_get_node_status`	CPU, memory, disk, swap, uptime, load averages
`pbs_list_tasks`	List recent tasks (filterable by type, status, running)
`pbs_get_task_status`	Get status and log output for a task UPID

Datastores

Tool	Description
`pbs_list_datastores`	List all datastores with retention config
`pbs_get_datastore_usage`	Storage usage, dedup factor, GC status
`pbs_list_groups`	List backup groups (vm/ct/host) in a datastore
`pbs_list_snapshots`	List snapshots, filterable by type/ID/namespace
`pbs_list_namespaces`	List namespaces in a datastore
`pbs_run_garbage_collection`	Start GC on a datastore
`pbs_run_verify`	Start verification on a datastore or group
`pbs_prune_datastore`	Prune a backup group (supports dry-run)
`pbs_protect_snapshot`	Protect or unprotect a snapshot from pruning

Jobs & Remotes

Tool	Description
`pbs_list_verification_jobs`	List scheduled verification jobs
`pbs_run_verification_job`	Manually trigger a verification job
`pbs_list_sync_jobs`	List configured sync jobs
`pbs_run_sync_job`	Manually trigger a sync job
`pbs_list_prune_jobs`	List scheduled prune jobs
`pbs_list_remotes`	List configured remote PBS servers

Related MCP server: mcp-server-proxmox

Setup

1. Install

npm install -g pbs-mcp-server

Or run directly without installing:

npx pbs-mcp-server

2. Create a PBS API Token

In the PBS web UI: Configuration → Access Control → API Tokens → Add

Give it the DatastoreAdmin or Admin role depending on what you need.

3. Configure environment variables

Copy .env.example and fill in your values:

cp .env.example .env

Key variables:

Variable	Required	Description
`PBS_HOST`	Yes	PBS IP or hostname (no port, no trailing slash)
`PBS_PORT`	No	API port, default `8007`
`PBS_TOKEN_ID`	Yes*	API token ID, e.g. `user@pbs!mytoken`
`PBS_TOKEN_SECRET`	Yes*	API token secret
`PBS_USERNAME`	Yes*	Username for ticket auth (alternative to token)
`PBS_PASSWORD`	Yes*	Password for ticket auth
`PBS_VERIFY_SSL`	No	Set to `false` for self-signed certs (default: `true`)
`TRANSPORT`	No	`stdio` (default) or `http`
`PORT`	No	HTTP mode port, default `3100`

*Either PBS_TOKEN_ID+PBS_TOKEN_SECRET or PBS_USERNAME+PBS_PASSWORD is required.

Claude Code (stdio)

claude mcp add --transport stdio pbs-mcp-server \
  -e PBS_HOST=192.168.1.10 \
  -e PBS_TOKEN_ID=user@pbs!mytoken \
  -e PBS_TOKEN_SECRET=your-secret \
  -e PBS_VERIFY_SSL=false \
  -- pbs-mcp-server

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pbs": {
      "command": "pbs-mcp-server",
      "env": {
        "PBS_HOST": "192.168.1.10",
        "PBS_TOKEN_ID": "user@pbs!mytoken",
        "PBS_TOKEN_SECRET": "your-secret",
        "PBS_VERIFY_SSL": "false"
      }
    }
  }
}

HTTP Mode

Start the server in HTTP mode for use with SSE-capable clients:

TRANSPORT=http PBS_HOST=192.168.1.10 PBS_TOKEN_ID=user@pbs!mytoken \
  PBS_TOKEN_SECRET=your-secret PBS_VERIFY_SSL=false pbs-mcp-server

Health check: GET http://localhost:3100/health MCP endpoint: POST http://localhost:3100/mcp

Development

npm install
npm run build      # compile TypeScript
npm run dev        # watch mode

License

MIT

Available Tools

19 tools

pbs_get_datastore_usageGet Datastore UsageA

Read-onlyIdempotent

Get usage statistics for all datastores: total/used/available space, GC status, and deduplication factor.

Returns: For each datastore: name, total, used, available, percent used, GC last-run time, dedup factor, removed/pending bytes/chunks.

Inputs: no named parameters.

pbs_get_node_statusGet PBS Node StatusA

Read-onlyIdempotent

Returns detailed status of the PBS node: CPU usage, memory, disk, swap, load averages, uptime, and kernel version.

Returns:

CPU model, core count, and current usage percentage
Memory: free / total / used
Root filesystem: available / total / used
Swap: free / total / used
Uptime and load averages
Kernel version

Inputs: no named parameters.

pbs_get_task_statusGet PBS Task StatusA

Read-onlyIdempotent

Get the status and log output of a specific task by its UPID.

Args:

upid (string): The task UPID

Returns: Task status and log lines.

Inputs: upid (required).

pbs_get_versionGet PBS VersionA

Read-onlyIdempotent

Returns the Proxmox Backup Server version, release, and repository ID. Use this to confirm connectivity and check which PBS version is running.

Inputs: no named parameters.

pbs_list_datastoresList PBS DatastoresA

Read-onlyIdempotent

List all configured datastores on the PBS server with their paths, comments, and retention settings.

Returns: Array of datastores with name, path, comment, GC schedule, prune schedule, and keep-* retention counts.

Inputs: no named parameters.

pbs_list_groupsList Backup GroupsA

Read-onlyIdempotent

List all backup groups in a datastore. Groups are organized by backup type (vm, ct, host) and ID.

Args:

store (string): Datastore name
ns (string, optional): Namespace path (e.g. "ns1/ns2")

Returns: Array of backup groups with type, ID, last backup time, backup count, and owner.

Inputs: store (required), ns.

pbs_list_namespacesList NamespacesA

Read-onlyIdempotent

List backup namespaces in a datastore.

Args:

store (string): Datastore name
parent (string, optional): Parent namespace to list children of

Returns: Array of namespace paths and their comments.

Inputs: store (required), parent.

pbs_list_prune_jobsList Prune JobsA

Read-onlyIdempotent

List all configured scheduled prune jobs.

Returns: Array of prune jobs with ID, store, schedule, retention settings, namespace, and disabled status.

Inputs: no named parameters.

pbs_list_remotesList RemotesA

Read-onlyIdempotent

List all configured remote PBS servers used for sync jobs.

Returns: Array of remotes with name, host, port, auth-id, fingerprint, and comment.

Inputs: no named parameters.

pbs_list_snapshotsList SnapshotsA

Read-onlyIdempotent

List snapshots in a datastore, optionally filtered by backup type and ID.

Args:

store (string): Datastore name
backup_type (string, optional): Filter by type — "vm", "ct", or "host"
backup_id (string, optional): Filter by backup ID (e.g. "100")
ns (string, optional): Namespace path

Returns: Array of snapshots with type, ID, timestamp, size, protection status, verification state, and file list.

Inputs: store (required), ns, backup_id, backup_type.

pbs_list_sync_jobsList Sync JobsA

Read-onlyIdempotent

List all configured sync jobs that replicate data between PBS servers.

Returns: Array of sync jobs with ID, local store, remote name, remote store, schedule, remove-vanished flag, namespace settings, and comments.

Inputs: no named parameters.

pbs_list_tasksList PBS TasksA

Read-onlyIdempotent

List recent tasks on the PBS node. Returns task UPID, type, user, start/end times, and status.

Args:

limit (number): Max tasks to return (default 30, max 200)
running (boolean): If true, only show currently running tasks
typefilter (string): Filter by task type, e.g. "garbage_collection", "verify", "prune", "sync"
statusfilter (string): Filter by status, e.g. "ok", "error"

Returns: List of tasks with UPID, type, user, timestamps, and completion status.

Inputs: limit, running, typefilter, statusfilter.

pbs_list_verification_jobsList Verification JobsA

Read-onlyIdempotent

List all scheduled verification jobs configured on the PBS server.

Returns: Array of verification jobs with ID, store, schedule, ignore-verified flag, outdated-after, namespace, and comment.

Inputs: no named parameters.

pbs_protect_snapshotProtect/Unprotect SnapshotA

Idempotent

Set or remove protection on a backup snapshot. Protected snapshots cannot be pruned or deleted.

Args:

store (string): Datastore name
backup_type (string): "vm", "ct", or "host"
backup_id (string): Backup ID
backup_time (string): Backup timestamp in ISO format (e.g. "2025-03-22T04:00:00Z")
protected (boolean): true to protect, false to unprotect
ns (string, optional): Namespace path

Returns: Confirmation of the protection change.

Inputs: store (required), backup_id (required), protected (required), backup_time (required), +2 more.

pbs_prune_datastorePrune DatastoreA

Destructive

Run a prune operation on a backup group to remove old snapshots per retention policy. Supports dry-run mode.

Args:

store (string): Datastore name
backup_type (string): Backup type — "vm", "ct", or "host"
backup_id (string): Backup ID (e.g. "100")
dry_run (boolean, optional): If true, only show what would be pruned (default false)
keep_last (number, optional): Keep the last N snapshots
keep_hourly (number, optional): Keep N hourly snapshots
keep_daily (number, optional): Keep N daily snapshots
keep_weekly (number, optional): Keep N weekly snapshots
keep_monthly (number, optional): Keep N monthly snapshots
keep_yearly (number, optional): Keep N yearly snapshots
ns (string, optional): Namespace path

Returns: Task UPID or dry-run results showing which snapshots would be removed/kept.

Inputs: store (required), backup_id (required), backup_type (required), ns, +7 more.

pbs_run_garbage_collectionRun Garbage CollectionA

Start a garbage collection job on a datastore. Returns the task UPID which can be tracked with pbs_get_task_status.

Args:

store (string): Datastore name

Returns: Task UPID for the started GC job.

Inputs: store (required).

pbs_run_sync_jobRun Sync JobA

Manually trigger a configured sync job by ID.

Args:

id (string): Sync job ID

Returns: Task UPID for the started job.

Inputs: id (required).

pbs_run_verification_jobRun Verification JobA

Manually trigger a configured verification job by ID.

Args:

id (string): Verification job ID

Returns: Task UPID for the started job.

Inputs: id (required).

pbs_run_verifyRun VerificationA

Start a verification job on a datastore to check backup integrity. Returns a task UPID.

Args:

store (string): Datastore name
backup_type (string, optional): Only verify this backup type
backup_id (string, optional): Only verify this backup ID
ignore_verified (boolean, optional): Skip already-verified snapshots (default true)
outdated_after (number, optional): Re-verify if last verification is older than this many days
ns (string, optional): Namespace path

Returns: Task UPID for the started verification job.

Inputs: store (required), ns, backup_id, backup_type, +2 more.

Tool Schema Changelog

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

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-08-05 02:10 across 19 tools

Disambiguation5/5

Each tool has a clearly distinct purpose, targeting specific resources (version, node, datastores, groups, snapshots) or actions (list, get, run, protect, prune). The two verification-related tools are differentiated by direct execution vs. triggering a configured job.

Naming Consistency5/5

All tools follow a consistent pattern with the pbs_ prefix and snake_case, using verb_noun structures like 'get_', 'list_', 'run_', and 'protect_'. The slight deviation of 'prune_datastore' as an imperative is still clear and doesn't break the overall consistency.

Tool Count4/5

With 19 tools, the set is on the higher end but remains well-scoped for a Proxmox Backup Server management surface. Each tool covers a distinct aspect of status, datastores, maintenance, jobs, and tasks, justifying the count without being bloated.

Completeness4/5

The tool set comprehensively covers monitoring, listing, and running maintenance tasks like garbage collection, verify, and prune. Missing create/update/delete operations for datastores, jobs, and remotes, but these are likely outside the intended operational scope and common workflows are fully supported.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

gainium-mcp
io.gainium
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Cryptocurrency Finance
22
https://mcp.gainium.io/mcp
hithereiamaliff-mcp-nextcloud
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
https://server.smithery.ai/@hithereiamaliff/mcp-nextcloud/mcp
mcp-openai
io.github.AceDataCloud
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
AI & Machine Learning Image & Video Processing
11
https://openai.mcp.acedata.cloud/mcp
Station Zero
services.stationzero
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Knowledge & Memory File Systems Workplace & Productivity
1
https://stationzero.services/mcp

Related MCP Servers

pbs-mcp
Virtualization Monitoring
ahmetem
A
license
A
quality
C
maintenance
MCP server for Proxmox Backup Server. Exposes datastore status, snapshot inventory, garbage collection, verify, and prune over the PBS REST API as 13 LLM-callable tools.
Updated 2 months ago (2026-09-05 16:35 UTC)
17
1
GPL 3.0
mcp-server-proxmox
Virtualization Cloud Platforms
heybearc
A
license
B
quality
C
maintenance
A Model Context Protocol (MCP) server for Proxmox Virtual Environment that enables AI assistants to manage virtual machines, containers, nodes, and resources through natural language interactions.
Updated 15 days ago (2026-10-26 12:16 UTC)
10
4
MIT
proxmox-mcp
Virtualization Cloud Platforms
LeonRLewis
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.
Updated 4 months ago (2026-06-30 21:52 UTC)
-
pve-mcp
Virtualization Shell Access
tiancode
A
license
A
quality
D
maintenance
MCP server for managing Proxmox VE resources, VM/CT lifecycle, snapshots, backups, and clones via natural language.
Updated 4 months ago (2026-07-06 23:39 UTC)
23
MIT

pbs-mcp-server

Tools

Node & System

Datastores

Jobs & Remotes

Setup

1. Install

2. Create a PBS API Token

3. Configure environment variables

Claude Code (stdio)

Claude Desktop

HTTP Mode

Development

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

pbs-mcp

mcp-server-proxmox

proxmox-mcp

pve-mcp