drumfire-proxmox-mcp

Ein Remote-MCP-Server, der es Claude ermöglicht, den DRUMFIRE-Proxmox-Cluster per Chat zu verwalten — Inventar, Energieverwaltung, Live-Konfigurationsänderungen, Erstellen/Klonen von VMs und Containern, Snapshots, Netzwerk-/Firewall-/Cluster-Sichtbarkeit, Ausführen von Befehlen innerhalb eines Gasts und das direkte Schreiben einer Datei auf das Dateisystem einer VM über den QEMU Guest Agent (hier verwendet, um den Net-Worth-Rechner auf VM 107 mit einem frischen Export aus Firefly III zu aktualisieren).

Es ist ein Cloudflare Worker, der auf dieselbe Weise bereitgestellt wird wie der bestehende Firefly-III-MCP-Server: Button klicken, ein paar Secrets setzen, als benutzerdefinierten Connector zu Claude hinzufügen.

Was er bewusst NICHT tut

Es gibt keine Lösch-Tools für VMs/Container/Datenträger/Snapshots und keine Rollback-Tools für Snapshots – kein „vorher fragen“, sondern schlicht nicht im Code vorhanden, sodass sie über diesen Server nicht einmal versehentlich passieren können.

Das heißt aber: Lies den Sicherheitshinweis unten. Da das Erstellen von VMs/Containern im Aufgabenbereich liegt, kann das zugrunde liegende Proxmox-Token technisch gesehen ebenfalls Löschungen vornehmen (Proxmox bündelt diese Berechtigungen) – die Garantie hier ist softwarebasiert (ein solches Tool existiert nicht, und Claude ist angewiesen, immer zu fragen, bevor etwas Destruktives geschieht), keine harte Mauer auf Credential-Ebene, wie es bei v1 dieses Servers der Fall war. Siehe „Sicherheitsmodell“ weiter unten.

Related MCP server: proxmox-mcp

Tools dieses Servers

Sicherheitsmodell

• Tools für Energieverwaltung/Status/Konfiguration/Erstellung/Klonen/Snapshot-Erstellung: gelten als „fair game“ im Sinne deiner Abgrenzung und dürfen ohne vorherige Rückfrage ausgeführt werden – nichts hiervon ist inhärent destruktiv.

• run_guest_command: führt aus, was ihm im Gast aufgetragen wird, gleichbedeutend mit SSH-/RDP-Zugriff. Gut für Diagnosen und Routineänderungen; Claude ist angewiesen, innezuhalten und bei dir nachzufragen, bevor im Gast etwas Destruktives oder Unumkehrbares passiert.

• Nichts in diesem Server löscht eine VM, einen Container, einen Datenträger oder einen Snapshot und führt bei ihnen kein Rollback durch. Das ist die eigentliche Absicherung, nicht die Berechtigungen des Proxmox-Tokens – siehe die Rolle unten, die sehr wohl VM.Allocate gewährt (erforderlich für das Erstellen, und Proxmox verwendet sie auch zum Löschen – es gibt keine Möglichkeit, das auf Berechtigungsebene zu trennen).

1. Ein Proxmox-API-Token mit begrenztem Umfang erstellen

Verwende kein Root-/Admin-Token. In der Proxmox-Web-UI:

1. Datacenter → Permissions → Roles → Create Name: ClaudeHomelabOps. Berechtigungen: VM.Audit, VM.Monitor, VM.PowerMgmt, Sys.Audit, VM.Allocate, VM.Clone, VM.Snapshot, VM.Config.CPU, VM.Config.Memory, VM.Config.Disk, VM.Config.Network, VM.Config.Options, VM.Config.HWType, VM.Config.CDROM, VM.Config.Cloudinit.

   Schließt bewusst VM.Snapshot.Rollback aus (ein Rollback verwirft den aktuellen Datenträgerzustand – wirklich destruktiv) sowie VM.Backup/VM.Migrate/VM.Console (für nichts von dem nötig, was dieser Server tut). Wie oben erwähnt, ist VM.Allocate für create_vm/create_container/clone_vm erforderlich, und Proxmox verwendet es auch zum Löschen von Gästen – es gibt keine feinere Trennung auf Berechtigungsebene, daher stammt die „kann nicht löschen“-Garantie hier schlicht daher, dass dieser Server kein Lösch-Tool besitzt, nicht von den Berechtigungen des Tokens.

   Wenn du die härtere Garantie auf Credential-Ebene im Alltag lieber beibehalten und die Erstellung nur vorübergehend gewähren möchtest, kannst du stattdessen ein zweites, stärker eingeschränktes Token erstellen (dieselbe Rolle ohne VM.Allocate/VM.Config.*) und umschalten, welches Secret dieser Worker verwendet, wenn du tatsächlich etwas erstellen/neu konfigurieren möchtest – die frühere Abwägungsfrage hat der Einfachheit halber standardmäßig ein Token gewählt, aber nichts hier erfordert das.

2. Datacenter → Permissions → Users → Add einen dedizierten Benutzer hinzufügen, z. B. claude-agent@pve (kein Passwort nötig, er authentifiziert sich ausschließlich über das API-Token).

3. Datacenter → Permissions → Add → Pfad /, Benutzer claude-agent@pve, Rolle ClaudeHomelabOps.

4. Datacenter → Permissions → API Tokens → Add → Benutzer claude-agent@pve, Token-ID z. B. homelab-mcp. Lasse „Privilege Separation“ aktiviert und gewähre dem Token selbst dieselbe / → ClaudeHomelabOps-ACL. Kopiere die Token-ID (claude-agent@pve!homelab-mcp) und das Secret (wird nur einmal angezeigt) – du benötigst beides weiter unten.

2. Sicherstellen, dass der Gast-Agent der Net-Worth-Rechner-VM aktiviert ist

Die Tools write_vm_file / update_networth_calculator benötigen den QEMU Guest Agent, der in VM 107 (VM-OnPremTest) läuft:

1. Stelle im Tab Options der VM in Proxmox sicher, dass „QEMU Guest Agent“ aktiviert ist.

2. Installiere in der Windows-VM den Gast-Agent-Dienst, falls er noch nicht installiert ist (er ist auf der virtio-win-ISO als qemu-ga-x86_64.msi enthalten), und stelle sicher, dass der Windows-Dienst „QEMU Guest Agent“ läuft.

3. Notiere, unter welchem Windows-Benutzerkonto der Datenordner der App liegt – der Gast-Agent-Dienst läuft als SYSTEM, daher benötigen Dateischreibvorgänge einen vollständigen absoluten Pfad, z. B. C:\Users\<username>\Documents\net-worth\data.json, keinen relativen.

3. Bereitstellen

(Pushe dieses Repo zuerst auf GitHub und ersetze dann REPLACE_WITH_THIS_REPO_URL oben durch https://github.com/<you>/<repo> – GitHub erlaubt es dem Button nicht, auf sich selbst zu verlinken, bevor das Repo existiert.)

Ein Klick auf den Button forkt/verbindet das Repo mit Cloudflare Workers Builds und führt die Bereitstellung für dich aus. Nutzbar ist es aber noch nicht – siehe Schritt 4.

Manuelle Bereitstellung (Alternative zum Button)

npm install
npx wrangler secret put PROXMOX_TOKEN_ID
npx wrangler secret put PROXMOX_TOKEN_SECRET
npx wrangler secret put MCP_BEARER_TOKEN   # any long random string you generate
npx wrangler deploy

4. Nach der Bereitstellung die Secrets setzen

Egal, ob du den Button oder die CLI verwendet hast: Drei Secrets sind erforderlich und befinden sich bewusst nicht in diesem Repo (sie stehen nicht in wrangler.jsonc, was in Ordnung ist, da diese Datei öffentlich sein darf).

Setze sie im Cloudflare-Dashboard unter deinem Worker → Settings → Variables and Secrets → Add → Encrypt oder über npx wrangler secret put <NAME>.

Überprüfe außerdem die normale (nicht geheime) Variable NETWORTH_VM_PATH in wrangler.jsonc – sie wird mit einem Platzhalter (C:\Users\CHANGE_ME\Documents\net-worth\data.json) ausgeliefert, der den echten Windows-Benutzernamen aus Schritt 2 benötigt. Bearbeite sie im Cloudflare-Dashboard auf derselben Seite Variables and Secrets (als Klartext-Variable, nicht als Secret) oder bearbeite wrangler.jsonc und stelle erneut bereit.

5. Als benutzerdefinierten Connector zu Claude hinzufügen

Füge in den Connector-Einstellungen von Claude einen benutzerdefinierten Connector hinzu, der auf Folgendes zeigt:

https://<your-worker-subdomain>.workers.dev/mcp

Dieser Worker prüft jede Anfrage auf Authorization: Bearer <MCP_BEARER_TOKEN>, bevor er irgendetwas tut – ohne diesen Header erhält jeder Tool-Aufruf eine 401. Falls deine Claude-Connector-Konfiguration das Anhängen eines benutzerdefinierten Headers/API-Keys erlaubt, setze diesen Header dort. Falls nicht, gibt es zwei Optionen:

• Stattdessen eine Cloudflare Access-Richtlinie vor die Route des Workers setzen (empfohlen — das ist die Standardmethode, um einen persönlichen MCP-Endpunkt abzusichern, wenn der Client keinen benutzerdefinierten Header senden kann), oder

• Als Fallback mit geringerer Sicherheit die Bearer-Token-Prüfung in src/index.ts entfernen (fetch(), am Anfang der Funktion) und sich darauf verlassen, dass die URL des Workers selbst nicht erraten werden kann. Für alles, was Proxmox erreichen kann, ist das nicht zu empfehlen.

6. Ausprobieren

Sobald die Verbindung steht, sollten in einem Claude-Chat „liste die VMs auf drumfire03 auf“ oder „wie ist der Status von VM 107“ echte Daten zurückgeben. Für den Net-Worth-Workflow holt Claude Daten von Firefly III (bereits verbunden), erstellt das JSON, das der Rechner erwartet, und ruft update_networth_calculator mit diesem JSON als String auf.

Sobald das funktioniert, kannst du auch die neueren Tools ausprobieren — „prüfe den Zustand des Clusters“, „wie lautet die aktuelle IP von VM 107 gerade“, „klone VM-OnPremTest in eine Testkopie“, „gib der VM 4 Kerne“.

Hinweis zu Berechtigungen: Die genauen Anforderungen von Proxmox an Privilegien für Firewall-Regel- und einige Netzwerk-Lese-Endpunkte variieren je nach Version etwas, und die obige Rolle ist eine Best-Effort-Zuordnung, die nicht gegen deine spezifische Proxmox-Version getestet wurde. Wenn ein Tool-Aufruf mit einem 403 zurückkommt, enthält die Fehlermeldung die tatsächliche Antwort von Proxmox — die Lösung ist fast immer, ClaudeHomelabOps ein weiteres Privileg hinzuzufügen (in der Regel genügt es, erneut zu bestätigen, dass Sys.Audit auf / angewendet ist, nicht nur auf einen Unterpfad).