Getting started¶

1. Install¶

uvx (recommended)pipxDockerFrom source

uvx proxmox-ops-mcp --version

uv downloads and runs the latest release in an isolated environment. Nothing is installed globally.

pipx install proxmox-ops-mcp

docker pull ghcr.io/derdennis1012/proxmox-ops-mcp

Multi-arch (amd64, arm64), runs as an unprivileged user, ships with SBOM and provenance attestations.

git clone https://github.com/derdennis1012/proxmox-ops-mcp
cd proxmox-ops-mcp && uv sync
uv run proxmox-ops-mcp --version

Python 3.11 or newer is required for the non-Docker options.

2. Create an API token¶

On any node, as root:

pveum user add mcp@pve
pveum acl modify / --users mcp@pve --roles PVEAuditor
pveum user token add mcp@pve ops --privsep 1          # prints the secret once
pveum acl modify / --tokens 'mcp@pve!ops' --roles PVEAuditor

This is enough for every tool except backup_audit, because Proxmox hides backups from pure auditors. Proxmox setup covers backup visibility, write tiers and two ACL rules that commonly trip people up.

3. Check the connection¶

export PROXMOX_HOST=pve1.example.com
export PROXMOX_TOKEN_ID='mcp@pve!ops'
export PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
uvx proxmox-ops-mcp check

If you get an SSLError, the node certificate does not cover the address you are using. That is normal with IPs or VPN addresses. check prints the openssl command for a certificate pin; put the result into PROXMOX_TLS_FINGERPRINT.

4. Connect your MCP client¶

For Claude Code:

claude mcp add proxmox-ops --scope user \
  -e PROXMOX_HOST=pve1.example.com \
  -e PROXMOX_TOKEN_ID='mcp@pve!ops' \
  -e PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -- uvx proxmox-ops-mcp

Claude Desktop, Cursor, VS Code, OpenAI Codex, Gemini CLI, Hermes Agent, OpenClaw and Docker are covered step by step in Connect a client.

5. Ask something¶

Good first prompts:

"Triage my Proxmox cluster." The server also ships this as the triage_cluster prompt.
"Which guests have no backup from the last 24 hours?"
"Is the storage on all nodes healthy?"
"Which nodes need updates or a reboot?"
"Can I put pve2 into maintenance tonight? Give me the runbook." Also available as the prepare_maintenance prompt.

Compatibility¶

Environment	Status
Proxmox VE 9.2, single node, ZFS, local and CIFS backup storages	All tools verified live, write tools on an isolated test VM
Multi-node clusters, HA, Ceph	Covered by tests with realistic payloads, not yet verified live
Proxmox Backup Server storages	Verification state is read from the PVE storage listing; not yet verified live
Proxmox VE 8	Expected to work, not yet verified

If you run it somewhere new, the live test suite takes a minute. Report the result in an issue, whether it passes or fails.