proxmox-mcp-suite

Proxmox MCP Suite

Run your Proxmox VE cluster and Backup Server from Claude — deeply, safely, and without drowning the context window.

·

·

·

·

Two Model Context Protocol servers, packaged

as Claude Code plugins, that turn Claude into a capable Proxmox operator —

69 tools across virtualization and backup, engineered to run *inside an

LLM's context*: compact output, one-call health, inline task results, and a

two-tier safety model with dry-run previews and a tamper-evident audit trail.

⚡ Quick start

Prereq: Claude Code and `uv` (`uvx`). The servers run via `uvx` — nothing to `pip install` by hand.

/plugin marketplace add ahmetem/proxmox-mcp-suite
/plugin install proxmox-ve@proxmox-mcp-suite
/plugin install proxmox-backup@proxmox-mcp-suite

Export your Proxmox credentials (see Configuration), restart

Claude Code, and ask:

> *"How is the server? Any storage filling up?"* — one `proxmox_health_overview` call.

>

> *"Snapshot VM 102 as pre-upgrade, then reboot it."*

>

> *"Is my last backup of CT 200 healthy?"*

🎯 Why this suite

Most Proxmox MCP servers wrap the API and hand Claude raw JSON. This one is

built for the thing that actually constrains an agent — context — and for

not breaking your infrastructure.

> Modular by design — install only Proxmox VE, only PBS, or both.

📦 What's inside

`proxmox-ve` — 52 tools

Repo: `homelab-proxmox-mcp`

• Guests — list/status, create VM & LXC from scratch, clone, power, resize
• Snapshots — create / rollback / delete (data-loss gated)
• Backups — vzdump create / list / restore (refuses silent overwrite)
• Storage & disks — pools, usage breakdown, physical disks + SMART
• LVM / ZFS — VG/thin, full ZFS: pools, datasets, snapshots, scrub, send, properties, disk-prepare & provisioning
• Exec — guest-VM SSH, host SSH (free + a read-only allow-listed variant safe for agents), LXC `pct exec`, service control, log tail
• Forensics & self-heal — task list/logs, backup-job inspection, stale `@vzdump` snapshot cleanup that unblocks failing backups

`proxmox-backup` — 17 tools

Repo: `homelab-pbs-mcp`

• Datastores & snapshots — status, usage, list, protect/forget
• Maintenance — garbage collection, verify jobs, prune (with dry-run)
• Tasks — status and logs by UPID
• Read-only by default — write-side tools stay inert until `PBS_ALLOW_WRITE=true`

🛡️ Safety model

Read-only tools run freely. Everything that changes state requires `confirm=true`;

anything that destroys persistent data *additionally* requires

`i_understand_data_loss=true` — so Claude only fires these after you clearly ask.

• `dry_run` previews on the highest-consequence mutations (create VM/CT,

clone, restore) return the exact API call they *would* make (secrets masked),

without touching anything.

• Tamper-evident audit — every host/guest shell exec is appended to a

hash-chained log (SHA-256, or HMAC-SHA256 with `PROXMOX_AUDIT_HMAC_KEY`).

`proxmox_audit_verify` recomputes the chain and flags any altered, deleted,

or reordered line.

• Token auth, never root passwords — API tokens are revocable and scope the

blast radius.

⚙️ Configuration

Credentials are passed to the servers via environment variables — export them in

the shell that launches Claude Code (no secret is stored in the plugin).

Proxmox VE — required: `PROXMOX_HOST`, `PROXMOX_USER`, `PROXMOX_TOKEN_NAME`,

`PROXMOX_TOKEN_VALUE`. Optional: `PROXMOX_PORT`, `PROXMOX_VERIFY_SSL`, and the

SSH-backed tools' `PROXMOX_SSH_*`. → full list in the

server repo.

Proxmox Backup Server — required: `PBS_HOST`, `PBS_TOKEN_ID`,

`PBS_TOKEN_SECRET`, `PBS_NODE`. Optional: `PBS_VERIFY_TLS`,

`PBS_DEFAULT_DATASTORE`, and `PBS_ALLOW_WRITE` (gates GC/prune/forget). →

PBS server repo.

Verify servers loaded with `/mcp`.

🔧 How it runs

Each plugin launches its server with `uvx`, which fetches, installs and isolates

it automatically from PyPI (`pve-mcp`,

`pbs-mcp`) — no clone, no virtualenv, no

manual `pip install`. `uvx` caches the environment after the first launch, so

later starts are instant. To pin a specific release, set a plugin's `args` to

e.g. `["pve-mcp==1.2.0"]`.

🔒 Security notes

• Keep the Proxmox / PBS APIs on a trusted LAN or behind a VPN.
• Privilege-separate the API tokens; grant the narrowest role that works.
• Don't remove the `confirm` / `i_understand_data_loss` guards.

📄 License

GNU General Public License v3.0.

Not affiliated with or endorsed by Proxmox Server Solutions GmbH. "Proxmox" is a

trademark of its respective owner.