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.

Related MCP server: proxmox-mcp

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

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.