Proxmox Monitoring MCP Server

Read-only-Überwachung und Konfigurationsaudit für den Proxmox-IaaS-Cluster, bereitgestellt für Claude über MCP. Läuft lokal über stdio; es gibt keinen Schreibpfad irgendwo in diesem Paket (proxmox_mcp/client.py implementiert nur GET), und das API-Token verwendet die Rolle PVEAuditor, sodass Proxmox selbst den Nur-Lese-Zugriff erzwingt.

1. API-Token auf Proxmox erstellen (einmalig, als root auf einem beliebigen Knoten)

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

Der Befehl token add gibt das Geheimnis einmal aus — kopieren Sie es sofort. Bei Privilegientrennung (--privsep 1) sind die effektiven Rechte des Tokens die Schnittmenge der ACLs von Benutzer und Token; deshalb muss PVEAuditor beiden zugewiesen werden (der vierte Befehl ist der, den jeder vergisst).

GUI-Entsprechung: Datacenter → Permissions → Users → Add; Datacenter → Permissions → API Tokens → Add; dann Datacenter → Permissions → Add → sowohl eine User Permission als auch eine API Token Permission auf Pfad /, Rolle PVEAuditor, Propagate aktiv.

Related MCP server: proxmox-mcp

2. Konfiguration und Installation (auf diesem Rechner)

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. Registrierung bei 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 prüft: Backup-Abdeckung, veraltete Snapshots, Speicher >85 %, Knotenspeicher >90 %, Speicher-Overcommit >1,5x, CPU-Overcommit >4x, PVE-Versionsabweichungen zwischen den Knoten, Standard-CPU-Typ kvm64, deaktivierter Gast-Agent, Datenträger am IDE-Bus und Aufgaben, die in den letzten 48h fehlgeschlagen sind. Die Schwellenwerte sind in .env einstellbar.

Drei MCP-Prompts werden mit dem Server mitgeliefert (in claude.ai unter "Add from proxmox-monitor" sichtbar): Cluster Config Audit, Cluster Health Brief, Backup Coverage Check.

Bereitstellung für das Team (remote, Entra-authentifiziert)

Der Server ist dual-transportfähig. MCP_TRANSPORT=stdio (Standard) ist für lokales Claude Code gedacht; MCP_TRANSPORT=http stellt streambares HTTP mit Microsoft-Entra-ID-Authentifizierung im Resource-Server-Modus bereit, gemäß ~/.claude/context/mcp-server-playbook.md.

• Entra: scripts/setup_entra_app.ps1 richtet die App ein, den access_as_user-Bereich, beide Claude-Redirect-URIs, v2-Tokens, das Client-Geheimnis und die Sicherheitsgruppe Proxmox-MCP-Users mit ihren Mitgliedern. Führen Sie es zuerst mit -ResolveOnly aus, um zu prüfen, ob die Teammitgliederliste aufgelöst werden kann. Details und das manuelle Vorgehen: docs/ENTRA_SETUP_CHECKLIST.md.

• Bereitstellung: Host-Port 8119 auf 10.0.0.10, öffentlicher Hostname proxmox-mcp.example.com. Schritte, Stack-Variablen und die NPM-Proxy-Host-Konfiguration: PORTAINER_DEPLOY.md.

Das Deployment ist blockiert, bis die Wartung der default-address-pools des Docker-Hosts durchgeführt ist — er ist bei 31/31 Netzwerken, sodass jeder neue Stack bei der Erstellung fehlschlägt. Die Entra-Registrierung kann jetzt durchgeführt werden; der Stdio-Server arbeitet in der Zwischenzeit weiter.

Tests

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

Sie benötigen keine Proxmox-Verbindung. Sie prüfen, dass jedes Tool und jeder Prompt registriert ist, dass jeder Prompt seinen eigenen Connector benennt (Vokabulare kollidieren über ein Dutzend verbundener Connectors hinweg), dass ProxmoxClient keine mutierende Methode erhalten hat und dass die Authentifizierung sich weigert, halb konfiguriert zu starten.