proxmox-ve-mcp

Ein MCP-Server, der einen oder mehrere Proxmox VE-Hosts als Werkzeuge bereitstellt, die ein LLM-Client aufrufen kann – Inventar von Nodes, Gästen, Speicher und Netzwerk-Bridges, Live-Status abrufen und VMs und Container erstellen, klonen, starten, stoppen und löschen.

Es spricht MCP über Streamable HTTP, sodass es als eigener Dienst im Netzwerk läuft und nicht als lokaler Unterprozess eines Clients.

Entwickelt für universal-network-director, einen chatgesteuerten Multi-Vendor-Netzwerkmanager mit einer menschlichen Genehmigungsschranke bei jedem Schreibvorgang – aber es ist ein eigenständiger MCP-Server und funktioniert mit jedem MCP-Client.

Nicht verbunden mit, unterstützt von oder befürwortet durch die Proxmox Server Solutions GmbH. „Proxmox“ und „Proxmox VE“ sind Marken ihrer jeweiligen Eigentümer und werden hier nur verwendet, um zu beschreiben, womit diese Software kommuniziert.

Lesen Sie dies, bevor Sie es auf die Produktion anwenden

Zwölf der vierundzwanzig Werkzeuge ändern den Zustand, und dieser Server fragt nicht vor der Ausführung. Es gibt keine Bestätigung und keinen Probelauf. Wenn ein Modell beschließt, eines aufzurufen, geschieht es.

Drei Möglichkeiten, damit umzugehen, in der Reihenfolge, in der sie tatsächlich helfen:

1. Beschränken Sie das Proxmox-API-Token auf schreibgeschützt. Dies ist die eigentliche Kontrolle und liegt auf Proxmox, nicht in diesem Code. Weisen Sie dem Token die integrierte Rolle PVEAuditor unter dem Pfad / zu, und jedes Schreibwerkzeug schlägt an der API fehl, egal was ein Modell entscheidet. Tun Sie dies, es sei denn, Sie beabsichtigen ausdrücklich, dass die Schreibvorgänge funktionieren.

2. Verwenden Sie die Sperrliste für geschützte Gäste. config/protected-vms.json listet Gäste auf, die die Schreibwerkzeuge nicht anfassen dürfen, lokal geprüft vor jedem Backend-Aufruf – sie gilt also auch, wenn ein Mensch versehentlich etwas genehmigt. Eine fehlende oder nicht analysierbare Datei verweigert jeden Gast-Schreibvorgang, anstatt stillschweigend nichts zu schützen. Siehe unten.

3. Schalten Sie die Schreibvorgänge in Ihrem Client frei. Jedes zustandsändernde Werkzeug hat das Präfix write_. Dieses Präfix ist eine Konvention dieser Codebasis, damit ein Client darauf abgleichen und diese Aufrufe vor der Ausführung durch einen menschlichen Genehmigungsschritt leiten kann. Dieser Server tut das bewusst nicht selbst – er hat keinen Benutzer, den er fragen könnte.

Der MCP-Endpunkt hat keine Authentifizierung

Dieser Server stellt seine Werkzeuge jedem zur Verfügung, der seinen Port erreichen kann. Es gibt kein Token, keine Client-Authentifizierung, kein TLS auf der MCP-Seite.

MCP_HOST standardmäßig auf 127.0.0.1 aus diesem Grund. Das Container-Image setzt 0.0.0.0, weil es muss, was bedeutet: Das Veröffentlichen des Container-Ports legt eine nicht authentifizierte Steuerungsebene für Ihre Hypervisoren auf dieses Interface. Halten Sie es in einem internen Netzwerk mit dem Client oder terminieren Sie TLS und Authentifizierung davor.

Multi-Host von Grund auf

Proxmox-Cluster teilen sich eine API, aber viele Setups betreiben mehrere eigenständige Hosts in verschiedenen Subnetzen ohne Cluster zwischen ihnen. Dieser Server hält eine Verbindung pro Host, identifiziert durch ein kurzes freies Label, und jedes Werkzeug nimmt dieses Label, um auszuwählen, mit welchem Host es spricht.

Ein Host wird durch ein Paar von Umgebungsvariablen definiert:

PROXMOX_SERVER1_URL=https://pve1.example.com:8006
PROXMOX_SERVER1_TOKEN='automation@pve!mcp=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Das <LABEL> in PROXMOX_<LABEL>_URL, kleingeschrieben, wird zum host-Wert, den die Werkzeuge verwenden (server1 oben). Fügen Sie einen dritten Host hinzu, indem Sie ein drittes Paar hinzufügen – keine Codeänderung. Benennen Sie sie nach dem Standort, damit das Modell und die Protokolle klar lesbar sind.

Das Token ist die gesamte Zeichenfolge user@realm!tokenid=secret, die einmalig bei der Erstellung unter Datacenter → Permissions → API Tokens angezeigt wird. Die Authentifizierung ist zustandslos: Jede Anfrage trägt einen Authorization: PVEAPIToken=...-Header. Es gibt keinen Login-Aufruf und kein CSRF-Token – das ist der Benutzername/Passwort-Session-Pfad, den dies bewusst nicht verwendet.

Setzen Sie PROXMOX_VERIFY_TLS=false für Hosts mit selbstsignierten Zertifikaten. Standardmäßig ist es aktiviert.

Die Sperrliste für geschützte Gäste

config/protected-vms.json wird schreibgeschützt in den Container eingebunden und enthält die Gäste, die Schreibwerkzeuge niemals berühren dürfen:

{
  "protected_vms": [
    {
      "host": "server1",
      "vmid": 100,
      "name": "example-mcp-host",
      "reason": "EXAMPLE -- the VM this MCP server itself runs in"
    }
  ]
}

host ist das Label aus list_hosts, nicht der Proxmox-Node-Name. reason wird wörtlich in der Ablehnung angezeigt, also schreiben Sie es für denjenigen, der darauf stößt.

Diese Datei soll in Git nachverfolgt werden. Sie begann als Umgebungsvariable in einer nicht verfolgten .env, was bedeutete, dass der Schutz einen frischen Klon nicht überlebte und eine leere Liste genauso aussah wie eine gefüllte. Jetzt verweigert eine fehlende oder nicht analysierbare Datei jeden Gast-Schreibvorgang; eine leere Liste ist erlaubt, protokolliert jedoch eine laute Warnung beim Start.

Die hier mitgelieferten Einträge sind Beispiele. Ersetzen Sie sie, bevor Sie dies auf etwas anwenden, das Ihnen wichtig ist.

Ausführen

docker build -t proxmox-ve-mcp .
docker run --rm \
  -e PROXMOX_SERVER1_URL=https://pve1.example.com:8006 \
  -e PROXMOX_SERVER1_TOKEN='automation@pve!mcp=...' \
  -e PROXMOX_VERIFY_TLS=false \
  -v "$PWD/config/protected-vms.json:/app/config/protected-vms.json:ro" \
  -p 127.0.0.1:8002:8002 \
  proxmox-ve-mcp

Oder installieren Sie pip install -r requirements.txt in einer virtuellen Umgebung und führen Sie python server.py direkt aus.

Tests

Eigenständige Skripte, kein pytest. Führen Sie sie im Container aus, damit sie die PROXMOX_*-Umgebung haben, die der Client benötigt:

docker run --rm proxmox-ve-mcp python test_network_bridges.py
docker run --rm proxmox-ve-mcp python test_media_in_use.py
docker run --rm proxmox-ve-mcp python test_client.py

Die Offline-Abschnitte verwenden erfundene Schnittstellen- und Gastlisten und bestehen ohne konfigurierte Hosts. Die Live-Abschnitte lesen, worauf Ihre PROXMOX_*-Variablen zeigen, und überspringen sauber, wenn nichts konfiguriert ist – zeigen Sie sie auf einen echten Host, um die eine Unterscheidung zu üben, die nicht vorgetäuscht werden kann: ob eine Bridge angebunden oder isoliert ist.

Design-Notizen

• /cluster/resources ist das Inventar-Rückgrat. Ein Aufruf gibt jede VM, jeden Container, Node und Speicher zurück, bereits mit Node, vmid und Typ gekennzeichnet. Es funktioniert auch auf einem eigenständigen Host (es meldet diesen einen Node), daher wird dies verwendet, anstatt pro Node /nodes → /nodes/{node}/qemu zu durchlaufen.

• list_network_bridges existiert, weil eine NIC auf der falschen Bridge ein Gast ist, den Sie nicht erreichen können. Es meldet pro Bridge, ob sie einen Mitgliedsport (einen Weg aus der Box) hat oder ein isoliertes Segment ist – die Unterscheidung, die entscheidet, ob eine neue VM erreichbar hochkommt.

• VLAN-Tags schlagen geschlossen fehl. Ein tag= auf einer Bridge, die nicht bridge_vlan_aware ist, wird von Proxmox akzeptiert und dann stillschweigend nicht übertragen – ungetaggter Verkehr, wo Isolation verlangt wurde. Die Schreibpfade lehnen dies ab, anstatt zu warnen, und lehnen ab, wenn sie die Bridge-Liste nicht lesen können, um zu prüfen.

• Schreibvorgänge sind asynchron. Die meisten geben eine Proxmox-UPID zurück; fragen Sie sie mit get_task_status ab, anstatt auf Abschluss zu warten.

• Gast-Schreibvorgänge laufen hinter einer Absicherung. Ein einzelner Wrapper führt die Prüfung auf geschützte VMs und die Auflösung von vmid→Node/Art durch, sodass ein einzelnes Werkzeug die Absicherung nicht vergessen kann und das Backend für einen geschützten Gast nicht erreichen kann.

Lizenz

Apache-2.0. See LICENSE.