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.

Related MCP server: ProxmoxMCP

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:

1. npm run lint

2. npm run typecheck

3. npm run build

4. npm test

5. npm audit --include=dev --audit-level=moderate

6. npm ls express

7. npm ls path-to-regexp

8. npm pack --dry-run

9. npm pack

10. npm whoami

11. npm publish --access public

12. npm view nandi-proxmox-mcp version

13. mcp-publisher validate .mcp/server.json

14. 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

• docs/QUICKSTART.md

• docs/PERMISSIONS.md

• docs/SECURITY.md

• docs/THREAT_MODEL.md

• docs/RELEASE.md

• docs/TROUBLESHOOTING.md

• docs/TOOLS.md

• docs/MARKETPLACE_GO_LIVE.md

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.