Proxmox Monitoring MCP Server

Read-only monitoring and config auditing for the Proxmox IaaS cluster, served to Claude over MCP. Runs locally over stdio; there is no write path anywhere in this package (proxmox_mcp/client.py only implements GET), and the API token uses the PVEAuditor role so Proxmox itself enforces read-only.

1. Create the API token on Proxmox (one time, as root on any node)

pveum user add claude-monitor@pve --comment "Read-only MCP monitoring"
pveum acl modify / --users claude-monitor@pve --roles PVEAuditor
pveum user token add claude-monitor@pve mcp --privsep 1
pveum acl modify / --tokens 'claude-monitor@pve!mcp' --roles PVEAuditor

The token add command prints the secret once — copy it immediately. With privilege separation (--privsep 1) the token's effective rights are the intersection of the user's and the token's ACLs, which is why PVEAuditor must be granted to both (the fourth command is the one everyone forgets).

GUI equivalent: Datacenter → Permissions → Users → Add; Datacenter → Permissions → API Tokens → Add; then Datacenter → Permissions → Add → both a User Permission and an API Token Permission on path /, role PVEAuditor, Propagate on.

2. Configure and install (this machine)

cd <your-workspace>/proxmox-mcp
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
cp .env.example .env    # then fill in PROXMOX_HOST / TOKEN_ID / TOKEN_SECRET

3. Register with Claude Code

claude mcp add proxmox --scope user -- <your-workspace>/proxmox-mcp/.venv/Scripts/python.exe <your-workspace>/proxmox-mcp/run_server.py

Tools

Tool	What it answers
capabilities	"What can this do?"
cluster_health	Quorum, node status, CPU/mem rollup
list_nodes / node_status	Per-host detail, versions, load
list_guests / guest_config	VM/LXC inventory and full configs
storage_status	Every datastore with usage
backup_status	Backup jobs + guests covered by no job
snapshot_audit	All snapshots with ages and RAM-state flag
recent_tasks	Failed (or all) recent cluster tasks
pending_updates	Packages awaiting install per node
config_audit	Flagship — every check below, graded warn/info

config_audit checks: backup coverage, stale snapshots, storage >85%, node memory >90%, memory overcommit >1.5x, CPU overcommit >4x, PVE version drift across nodes, default kvm64 CPU type, guest agent disabled, disks on the IDE bus, and tasks that failed in the last 48h. Thresholds are tunable in .env.

Three MCP prompts ship with the server (visible in claude.ai under "Add from proxmox-monitor"): Cluster Config Audit, Cluster Health Brief, Backup Coverage Check.

Serving it to the team (remote, Entra-authenticated)

The server is dual-transport. MCP_TRANSPORT=stdio (default) is local Claude Code; MCP_TRANSPORT=http serves streamable HTTP with Microsoft Entra ID auth in resource-server mode, per ~/.claude/context/mcp-server-playbook.md.

• Entra: scripts/setup_entra_app.ps1 provisions the app, the access_as_user scope, both Claude redirect URIs, v2 tokens, the client secret, and the Proxmox-MCP-Users security group with its members. Run it with -ResolveOnly first to check the teammate list resolves. Details and the manual fallback: docs/ENTRA_SETUP_CHECKLIST.md.
• Deploy: host port 8119 on 10.0.0.10, public hostname proxmox-mcp.example.com. Steps, stack variables and the NPM proxy-host config: PORTAINER_DEPLOY.md.

Deployment is blocked until the docker host's default-address-pools maintenance happens — it is at 31/31 networks, so any new stack fails at creation. The Entra registration can be done now; the stdio server keeps working meanwhile.

Tests

<your-workspace>/proxmox-mcp/.venv/Scripts/python.exe -m pytest tests -q

They need no Proxmox connection. They assert every tool and prompt is registered, that each prompt names its own connector (vocabulary collides across a dozen attached connectors), that ProxmoxClient has grown no mutating method, and that auth refuses to start half-configured.