NANDI Proxmox MCP

Verwandeln Sie Ihren Proxmox-Cluster in eine KI-gesteuerte Plattform mit über 140 Tools für Automatisierung, Überwachung und kontrollierte Ausführung.

Open-Source-MCP-Server für Proxmox VE, bereitgestellt von NANDI Services.

nandi-proxmox-mcp bietet Zugriff auf Proxmox-Bestände, Lebenszyklus, Speicher, Backups, Netzwerke, Firewalls, Zugriffskontrolle, Überwachung, SSH-Diagnose sowie geschützte Remote-/Container-Operationen, ohne die für Produktionscluster erforderlichen Sicherheitsvorkehrungen zu entfernen.

Was aktiviert bleibt

Über 140 Tools für Knoten, Cluster, QEMU, LXC, Speicher, Backups, Aufgaben, Netzwerk, Firewall, Pools, Zugriff, Vorlagen, Überwachung und Remote-Operationen.
Zugriffsebenen: read-only, read-execute, full.
Modulaufteilung: PVE_MODULE_MODE=core|advanced.
Tool-Filter: PVE_CATEGORIES, PVE_TOOL_BLACKLIST, PVE_TOOL_WHITELIST.
Sicherheitsvorkehrungen für destruktive Aktionen via confirm=true.
Abwärtskompatible Aliase wie listNodes, getVMStatus, startVM, stopContainer.
stdio-Transport für MCP-Clients und Streamable-HTTP-Transport für kontrollierte Remote-Bereitstellungen.

Erforderliche Berechtigungen

Der Server benötigt zwei Vertrauenskanäle, die beide bewusst beibehalten werden:

Proxmox-API-Token
- Wird für Bestands-, Lebenszyklus-, Konfigurations- und Verwaltungsendpunkte verwendet.
- Halten Sie ACLs minimal: Erteilen Sie nur die Rollen, die für die tatsächlich aktivierten Tools erforderlich sind.
SSH-Batch-Zugriff auf den Proxmox-Host
- Erforderlich für pct exec, Batch-SSH-Diagnosen und Docker-Inspektionstools auf Containerebene.
- Dies ist weiterhin notwendig, da die Proxmox-API-Abdeckung die hostseitigen pct- und SSH-basierten Diagnosen nicht ersetzt.

Weitere Details: docs/PERMISSIONS.md

Bestätigung destruktiver Aktionen

Als destruktiv markierte Operationen werden nicht ausgeführt, es sei denn, der Aufrufer sendet confirm=true.

Beispiele:

VM/Container stoppen, herunterfahren, neu starten, anhalten, löschen, migrieren, Snapshot-Rollback
Schreibzugriffe auf Speicher/Netzwerk/Firewall/Zugriff, die den Cluster-Status ändern können
Erweiterte Remote-Ausführung wie pve_exec_in_container

Der Server gibt einen strukturierten CONFIRMATION_REQUIRED-Fehler zurück, wenn die Bestätigung fehlt. Dieses Verhalten ist unverändert und verstärkt.

Zugriffsebenen

read-only
- Bestand, Status, Protokolle, Metriken und nicht-mutierende Diagnosen.
read-execute
- Nur-Lese-Zugriff plus ausgewählte Ausführungs-/Lebenszyklusaktionen.
full
- Erstellen, Aktualisieren, Löschen, Migrieren, Wiederherstellen und Operationen auf Admin-Ebene.

PVE_MODULE_MODE=core verbirgt erweiterte Tools, ohne die kanonischen Tool-IDs im Codebase umzubenennen oder zu entfernen.

Laufzeitkonfiguration

Umgebungsvariablen

Erforderlich:

PROXMOX_HOST
PROXMOX_USER
PROXMOX_REALM
PROXMOX_TOKEN_NAME
PROXMOX_TOKEN_SECRET
PROXMOX_SSH_HOST
PROXMOX_SSH_USER
PROXMOX_SSH_KEY_PATH

Optional:

PROXMOX_PORT Standard 8006
PROXMOX_SSH_PORT Standard 22
PROXMOX_ALLOW_INSECURE_TLS Standard false
PVE_ACCESS_TIER=read-only|read-execute|full
PVE_MODULE_MODE=core|advanced
PVE_CATEGORIES
PVE_TOOL_BLACKLIST
PVE_TOOL_WHITELIST

HTTP-Transport:

MCP_TRANSPORT=stdio|http
MCP_HOST Standard 0.0.0.0
MCP_PORT Standard 3000
MCP_ALLOWED_HOSTS
MCP_ALLOWED_ORIGINS
MCP_RATE_LIMIT_WINDOW_MS
MCP_RATE_LIMIT_MAX
MCP_MAX_BODY_SIZE_BYTES
MCP_HEADERS_TIMEOUT_MS
MCP_REQUEST_TIMEOUT_MS
MCP_KEEPALIVE_TIMEOUT_MS
MCP_MAX_HEADERS_COUNT

Lokale Konfigurationsdatei

Das Setup schreibt .nandi-proxmox-mcp/config.json und .vscode/mcp.json.

Der Konfigurations-Loader lehnt nun ab:

leere oder fehlerhafte Konfigurationspfade
zu große Konfigurationsdateien
Steuerzeichen in Konfigurationspfaden

Schnellstart

Geführtes Setup:

npx nandi-proxmox-mcp setup
npx nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op

Direkter Start mit Umgebungsvariablen:

$env:PROXMOX_HOST="pve.local"
$env:PROXMOX_PORT="8006"
$env:PROXMOX_USER="svc_mcp"
$env:PROXMOX_REALM="pve"
$env:PROXMOX_TOKEN_NAME="nandi-mcp"
$env:PROXMOX_TOKEN_SECRET="<SECRET>"
$env:PROXMOX_SSH_HOST="pve.local"
$env:PROXMOX_SSH_USER="root"
$env:PROXMOX_SSH_KEY_PATH="$env:USERPROFILE\.ssh\id_ed25519"

npx nandi-proxmox-mcp run

Sicherheitsmodell & Restrisiko

Dieser MCP-Server betreibt echte Proxmox-Infrastruktur und ist keine Sandbox-Umgebung.

Vertrauensannahmen

Der Server wird in einer vertrauenswürdigen Umgebung bereitgestellt
Nur autorisierte Bediener haben Zugriff
Die Netzwerkkonfiguration ist kontrolliert (nicht öffentlich zugänglich)
Anmeldedaten werden sicher verwaltet

Restrisiken

Die folgenden Risiken sind dem Systemdesign inhärent:

Privilegierte Operationen Die volle Zugriffsebene und die Möglichkeiten zur Containerausführung können destruktive oder systemweite Aktionen ausführen.
SSH-Ausführungsgrenze Die Remote-Befehlsausführung basiert auf SSH und erbt die Sicherheitslage des Zielsystems.
Optionaler unsicherer TLS-Modus Wenn aktiviert (PROXMOX_ALLOW_INSECURE_TLS=true), wird die TLS-Zertifikatsvalidierung umgangen, was Verbindungen für MITM-Angriffe anfällig machen kann. Nur für Laborzwecke gedacht.
Synchronisation externer Abhängigkeiten Die Paketverteilung und die Sichtbarkeit der Auflistung hängen von npm, der MCP-Registry und den Propagierungszeiten des Marktplatzes ab.

Sicherheitsverantwortlichkeiten

Benutzer sind verantwortlich für:

Die Beschränkung des Zugriffs auf vertrauenswürdige Bediener
Die Verwendung von API-Token und SSH-Schlüsseln mit minimalen Berechtigungen
Das Vermeiden von unsicherem TLS in Produktionsumgebungen
Die ordnungsgemäße Sicherung der zugrunde liegenden Infrastruktur

Implementierte Sicherheitskontrollen

Zugriffsebenen (read-only, read-execute, full)
Bestätigung für destruktive Operationen erforderlich
Eingabevalidierung und Befehlshärtung
Ratenbegrenzung und Anforderungsvalidierung

HTTP-Härtung

Wenn MCP_TRANSPORT=http aktiviert ist, wendet der Server nun Folgendes an:

Durchsetzung einer Host-Allowlist, einschließlich Schutz vor Wildcard-Bindungen
Ursprungsvalidierung für Anfragen, die einen Origin-Header senden
Explizite Limits für die Body-Größe und bereinigte 413-Antworten
Ratenbegrenzung auf /mcp
Timeouts für Anfragen/Header/Keep-Alive
X-Content-Type-Options: nosniff
Cache-Control: no-store
Bereinigte Fehler-Payloads ohne Stack-Traces

Health/Readiness-Endpunkte:

GET /health
GET /ready
POST /mcp

SSH- und Befehlsausführungshärtung

Die Funktionalität ist unverändert, aber der Ausführungspfad ist strenger:

Die lokale Befehlsausführung verwendet weiterhin spawn(..., { shell: false })
SSH-Host/Benutzer-Werte können keine CLI-Optionen einschleusen
SSH verwendet BatchMode, IdentitiesOnly, Public-Key-Authentifizierung und explizite Kontrollen für die Verbindungslebendigkeit
Ausgabepuffer sind begrenzt, um unbegrenztes Speicherwachstum zu verhindern
dockerLogsInContainer validiert und maskiert nun Containernamen, anstatt rohe Benutzereingaben zu interpolieren
Die willkürliche Ausführung von Container-Befehlen bleibt nur über den bereits destruktiven pve_exec_in_container-Ablauf mit erforderlicher Bestätigung verfügbar

Sicherheitslage

Mitigationen im Repo:

Fixierte direkte Abhängigkeitsversionen und npm overrides für kritische transitive Pakete
Überprüfbare Paketmetadaten und Repository-Links für npm/Paket-Scanner
Validierung der Deskriptor-/Versionssynchronisierung für npm, Registry und Marktplatz-Artefakte
Schwärzung von Token-/Header-/Passwort-ähnlichen Werten in Protokollen
Keine Stack-Traces oder Geheimnisse werden an Clients zurückgegeben
CI-Gates für Lint, Typecheck, Build, Tests, Metadatenvalidierung, Deskriptor-Sync, npm pack --dry-run und Audit

Bedrohungsmodell und Restrisiken: docs/THREAT_MODEL.md

Veröffentlichungsablauf

Die Release-Reihenfolge ist strikt:

npm run lint
npm run typecheck
npm run build
npm test
npm audit --include=dev --audit-level=moderate
npm ls express
npm ls path-to-regexp
npm pack --dry-run
npm pack
npm whoami
npm publish --access public
npm view nandi-proxmox-mcp version
mcp-publisher validate .mcp/server.json
mcp-publisher publish .mcp/server.json

Das tag-basierte release.yml veröffentlicht nun zuerst npm und erst danach den MCP-Registry-Deskriptor, um eine Drift zwischen npm und Registry bei derselben Version zu verhindern.

Manueller Fallback und Fehlerbehebung: docs/RELEASE.md

Entwicklung

npm ci
npm run lint
npm run typecheck
npm run build
npm test
npm run validate:release
npm pack --dry-run

Wartungsrichtlinie für Dokumentation

Dieses Repository erzwingt ein Pre-Commit-Gate für die Dokumentationssynchronisierung.

Bevor ein change, fix oder refactor geschlossen wird, ist zu prüfen, ob README.md, AGENTS.md und CONTRIBUTING.md aktualisiert werden müssen.
Wenn ein Dokument für die verhaltensbezogenen oder prozessualen Auswirkungen relevant ist, muss es im selben Änderungssatz aktualisiert werden.
Wenn kein Update erforderlich ist, ist eine explizite no-doc-change-Begründung erforderlich.
Eine Aufgabe gilt erst dann als bereit für den Commit, wenn dieses Gate erfüllt ist.

Dokumente

Registry und Marktplatz

npm: https://www.npmjs.com/package/nandi-proxmox-mcp
MCP Registry: https://registry.modelcontextprotocol.io/
MCP Marketplace-Eintrag: https://mcp-marketplace.io/server/io-github-nandi-services-nandi-proxmox-mcp

Lizenz

MIT. Siehe LICENSE.

nandi-proxmox-mcp