proxmox-mcp

An MCP server that lets an AI assistant fully navigate a single-node Proxmox VE host — inspect, control, provision, and destroy — without exposing any new network service.

The server runs on the Proxmox node itself, launched over SSH and speaking stdio. Nothing listens. There is no port, no API token, no TLS, and no daemon. The node's existing sshd is the only entry point, and your existing SSH key is the only credential.

Claude Code (your PC)  ──ssh──►  proxmox-mcp (on the node)  ──►  pvesh / qm / pct

Install on the node

From the Proxmox host, as root:

apt-get install -y git          # not present on a stock PVE install
git clone https://github.com/ssan9876/proxmox-mcp /opt/proxmox-mcp-src
/opt/proxmox-mcp-src/install.sh

The installer creates a venv at /opt/proxmox-mcp, installs the package, drops a launcher at /opt/proxmox-mcp/bin/proxmox-mcp, and writes a starter config to /etc/proxmox-mcp/config.yaml if none exists.

Verify it:

/opt/proxmox-mcp/bin/proxmox-mcp --dry-run --log-level DEBUG

It should log a startup line and then wait on stdin. Ctrl-C to exit.

Connect from your PC

You need password-less SSH to the node first:

ssh-copy-id root@pve

Then add the server to your MCP client. For Claude Code:

claude mcp add proxmox -- ssh -o BatchMode=yes root@pve /opt/proxmox-mcp/bin/proxmox-mcp --mode safe

Or by hand, in your MCP config:

{
  "mcpServers": {
    "proxmox": {
      "command": "ssh",
      "args": [
        "-o", "BatchMode=yes",
        "root@pve",
        "/opt/proxmox-mcp/bin/proxmox-mcp", "--mode", "safe"
      ]
    }
  }
}

Replace pve with your node's hostname or IP.

Modes

The mode decides which tools are registered. Tools outside the active mode are never exposed — the model cannot see them or call them.

Mode	What it can do
readonly	Inspect everything. Zero mutation.
safe	+ start/stop/reboot, create VMs and containers, snapshot, back up.
full	+ destroy, restore, roll back, shrink disks, run commands in guests, root shell on the host.

safe is the default. Change it per-connection with --mode in the SSH args, so the power a session has is visible in your client config. Keeping a second entry named proxmox-full and only enabling it when you need it is a reasonable setup.

Guardrails

Four checks sit in front of anything that can lose data:

1. Protected denylist — VMIDs, names, and pools listed in the config are refused by every destructive tool, including in full mode. Disruptive lifecycle actions (stop, reboot, shutdown) honour it too, and a disk whose volume ID belongs to a protected VMID is protected with it.
2. Mode gate — the tool must be registered by the active mode.
3. Confirm token — destructive tools require a confirm argument holding the target's exact token: vm:104, ct:110/snap:nightly, volume:local-lvm:vm-104-disk-0, node:pve, api:DELETE:/nodes/pve/.... A mismatch returns the target's real details — name, status, disks, uptime — so what was about to be destroyed is visible in the transcript before any retry.
4. Protective snapshot or backup — rollback_snapshot and shrink_disk snapshot first. destroy_guest and restore_backup cannot be protected by a snapshot, so they run vzdump first and abort if the backup fails.

node_shell is deliberately not gated on every call — requiring a constant token to run ls would just train the model to paste it. Instead it demands the node token only when the command matches a destructive pattern (rm -rf, mkfs, dd, zfs destroy, lvremove, reboot, apt purge, and similar).

What the confirm token is and is not

The mismatch error includes the expected token, so a model can read it and retry. That is deliberate: a token the caller cannot learn makes the tool unusable. What it buys is a blocked first attempt on a hallucinated or stale VMID, a forced second round-trip, and the target's details in front of you. It is not an authorization boundary. The denylist and the mode gate are.

Configuration

/etc/proxmox-mcp/config.yaml:

mode: safe              # readonly | safe | full
node: null              # auto-detected when null
auto_snapshot: true     # protective snapshots before lossy operations
task_poll_seconds: 10   # how long tools wait on a task before returning a UPID
command_timeout: 60
shell_timeout: 600      # ceiling for node_shell
max_output_bytes: 100000
protected:
  vmids: [100]
  names: ["opnsense", "truenas"]
  pools: ["production"]

CLI flags --mode, --config, --node, and --dry-run override the file.

Tools

Inspect (all modes) — resource_summary, node_status, list_guests, guest_config, guest_status, list_storage, storage_content, list_networks, list_tasks, task_log, list_snapshots, list_backups, node_services, read_syslog, list_access, node_updates

Lifecycle (safe+) — start_guest, shutdown_guest, stop_guest, reboot_guest, suspend_guest, resume_guest, wait_for_task

Provision (safe+) — create_vm, create_container, set_guest_config, grow_disk, clone_guest, create_snapshot, create_backup, convert_to_template, download_to_storage

Destructive (full) — destroy_guest, delete_snapshot, delete_volume, rollback_snapshot, restore_backup, shrink_disk, guest_exec, node_shell, node_reboot

Passthrough — pve_get and pve_discover in all modes; pve_post, pve_put, pve_delete in full. These reach every endpoint the Proxmox web UI uses, so anything the curated tools miss is still reachable.

resource_summary is the intended starting point: node health, every guest, and every storage in one call.

Development

git clone https://github.com/ssan9876/proxmox-mcp && cd proxmox-mcp
uv venv && uv pip install -e ".[dev]"
uv run pytest

Tests inject a fake command runner, so the whole suite runs on any machine with no Proxmox host involved. Tools are verified by asserting the exact pvesh argv they build and feeding recorded JSON back.

Notes

• Transport is stdio: stdout belongs to the MCP protocol. All logging goes to stderr. A stray print() corrupts the session.
• The server holds root on your hypervisor. In full mode it can delete VMs and run arbitrary commands. Run it in safe unless you are actively doing something that needs more.
• Tool results are capped at max_output_bytes so an unbounded journalctl or node_shell cannot exhaust the context window.