proxmox-mcp

Active

Driving a Proxmox cluster from the web UI means clicking through nodes, guests, and task logs one panel at a time. proxmox-mcp hands the whole cluster to your agent over API-token auth: inventory VMs and containers, boot or clone a guest, trace a UPID, and manage snapshots and backups in plain language, with a three-tier write gate so nothing changes state by accident.

GitHub repo → npm →

$npm i -g @solomonneas/proxmox-mcp (or npx -y @solomonneas/proxmox-mcp)

4 write tiersread-only CLIstdioNode 20+

See it workrepresentative session

you

CT 105 on the cluster feels sluggish. What is it doing, and can you snapshot it before I poke at it?

tool

proxmox_resource_usage{ vmid: 105 }

result

ct 105 wazuh node pve-01 cpu 94% mem 3.8/4.0 GiB disk 61% uptime 12d

tool

proxmox_snapshot_resource{ vmid: 105, name: "pre-triage", confirm: true }

result

UPID:pve-01:vzdump-snapshot:105 snapshot pre-triage created ok

agent

CT 105 is pinned at 94% CPU and 3.8 of 4.0 GiB memory, so it is memory-starved, not idle-slow. I took snapshot pre-triage so you can roll back safely. Bump its memory or check the wazuh indexer before you dig in.

Representative session. Illustrative values, RFC 5737 addresses. The write took confirm: true; destructive tools stay gated behind an env flag.

What it does

proxmox-mcp is an MCP server that turns a Proxmox VE cluster into tools an agent can call: cluster and node status, VM and LXC inventory, configs, RRD metrics, task tracing, snapshots, backups, gated guest reads and shell exec, and full provision/clone/destroy lifecycle, all over Proxmox API-token auth. It exists because your homelab lives in Proxmox and you want an assistant to inventory it or boot a guest without you clicking through the web UI or handing it a root shell. What sets it apart is the write-safety model: 96 tools split across four tiers where reads are open, safe writes need confirm: true, and destructive ops need confirm: true plus destructive: true plus a process-level PROXMOX_ENABLE_DESTRUCTIVE=1 env flag, so a hallucinated call fails closed before any HTTP traffic reaches Proxmox.

Capabilities96 tools across four write tiers

Cluster & guest reads

43 tools

Open, no flag. Cluster/node status, VM and LXC inventory, configs, storage, snapshots, backups, RRD usage, tasks, disks, HA/SDN/replication.

Access & firewall reads

included in reads

Users, roles, ACLs, pools, API tokens, and firewall rules/options inspected at cluster, node, or guest scope.

Gated guest reads

4 tools

Read files, stat paths, list directories, and check service state inside a guest over host-backed SSH. Require confirm: true.

Lifecycle safe-writes

41 tools

Start/stop/reboot, snapshot, backup, create/clone/migrate, config and disk edits, guest exec and write_file, service control. Require confirm: true.

Destructive ops

8 tools

Destroy, force-stop, rollback, delete snapshot/volume/storage, node power. Require confirm + destructive + PROXMOX_ENABLE_DESTRUCTIVE=1.

Full tool reference on GitHub →

Setup

01 · install

npm i -g @solomonneas/proxmox-mcp   (or npx -y @solomonneas/proxmox-mcp)

02 · configure

Set PROXMOX_URL, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET (all required). PROXMOX_TLS_INSECURE=false for homelab self-signed certs; PROXMOX_ENABLE_DESTRUCTIVE=1 to unlock tier-3.

03 · mcp client config

{ "mcpServers": { "proxmox": { "command": "npx", "args": ["-y", "@solomonneas/proxmox-mcp"], "env": { "PROXMOX_URL": "https://192.0.2.10:8006", "PROXMOX_TOKEN_ID": "pve-admin@pam!api-token-1", "PROXMOX_TOKEN_SECRET": "00000000-0000-0000-0000-000000000000", "PROXMOX_TLS_INSECURE": "false" } } } }

Safety

how it stays safe

Every tool's tier is enforced in code, not just documented. Reads are open; safe writes require confirm: true and throw WriteGateError before any HTTP call when the flag is missing; the 8 destructive tools also require destructive: true plus the process-level PROXMOX_ENABLE_DESTRUCTIVE=1 env flag, staying inert until you set it. The token secret is registered with a redactor at startup and masked from all log and error output. The bundled proxmoxctl CLI is read-only, so shells, cron, and CI never touch a write path. Recommended start: a read-only token (Datastore.Audit + VM.Audit + Sys.Audit), graded up only after confirming the gates hold.

More in Homelab5 tools

adguardctrlRun AdGuard Home DNS filtering from shells and agents, destructive writes gated. proxguardAudit Proxmox against CIS benchmarks: config parsers and remediation scripts. jellyctrlDrive Jellyfin libraries, sessions, and users from a CLI or MCP, writes gated. immichctrlOne typed control surface for Immich: search, albums, and duplicate audits. samba-ad-migrationAutomated migration of a Windows AD file share to Samba on Proxmox, with Winbind domain join and permission-preserving data copy.