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 in einem Gast sowie das direkte Übertragen einer Datei auf das Dateisystem einer VM über den QEMU-Gast-Agenten (hier genutzt, um den auf VM 107 laufenden Nettovermögensrechner 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, in Claude als benutzerdefinierten Connector hinzufügen.

Was er bewusst NICHT tut

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

Allerdings lies unbedingt den Sicherheitshinweis unten: Da das Erstellen von VMs/Containern im Scope liegt, kann das zugrunde liegende Proxmox-Token sie technisch gesehen ebenfalls löschen (Proxmox koppelt diese Berechtigungen) — die Garantie hier ist softwareseitig erzwungen (kein solches Tool existiert, und Claude ist angewiesen, vor allem, was destruktiv ist, immer zu fragen), keine harte Mauer auf Credential-Ebene wie bei v1 dieses Servers. Siehe „Sicherheitsmodell“ unten.

Related MCP server: ProxmoxEmCP

Tools, die dieser Server bereitstellt

Sicherheitsmodell

• Tools für Energieverwaltung/Status/Konfiguration/Erstellen/Klonen/Snapshot-Erstellung: gelten als „Freiwild“ und können ohne vorherige Rückfrage ausgeführt werden, entsprechend deiner Abgrenzung — nichts hiervon ist von Natur aus destruktiv.

• run_guest_command: führt innerhalb des Gastsystems aus, was ihm aufgetragen wird — gleichbedeutend mit SSH-/RDP-Zugriff. Gut für Diagnosen und Routineänderungen; Claude ist angewiesen, innezuhalten und mit dir Rücksprache zu halten, bevor es innerhalb des Gasts etwas tut, das destruktiv oder irreversibel aussieht.

• Nichts in diesem Server löscht eine VM, einen Container, einen Datenträger oder einen Snapshot oder führt ein 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 die Erstellung, und Proxmox verwendet sie auch für das Löschen — es gibt keine Möglichkeit, das auf Berechtigungsebene zu trennen).

1. Ein eingeschränktes Proxmox-API-Token erstellen

Verwende kein Root-/Admin-Token. In der Proxmox-Web-Benutzeroberfläche:

1. Rechenzentrum → Berechtigungen → Rollen → Erstellen 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.

   Bewusst ausgeschlossen sind VM.Snapshot.Rollback (Rollback verwirft den aktuellen Datenträgerzustand — wirklich destruktiv) und VM.Backup/VM.Migrate/VM.Console (für nichts erforderlich, was dieser Server tut). Wie oben behandelt, ist VM.Allocate für create_vm/create_container/clone_vm erforderlich, und Proxmox nutzt es auch für das Löschen von Gästen — eine feinere Aufteilung gibt es nicht, die Garantie „kann nicht löschen“ kommt also daher, dass dieser Server schlicht kein Lösch-Tool hat, nicht von den Berechtigungen des Tokens.

   Wenn du die strengere Garantie auf Credential-Ebene lieber im Alltag behalten 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 oder neu konfigurieren möchtest — die frühere Abwägungsfrage hat sich der Einfachheit halber für ein Token entschieden, aber nichts hier erfordert das.

2. Rechenzentrum → Berechtigungen → Benutzer → Hinzufügen einen dedizierten Benutzer, z. B. claude-agent@pve (kein Passwort nötig; er authentifiziert sich ausschließlich über das API-Token).

3. Rechenzentrum → Berechtigungen → Hinzufügen → Pfad /, Benutzer claude-agent@pve, Rolle ClaudeHomelabOps.

4. Rechenzentrum → Berechtigungen → API-Tokens → Hinzufügen → Benutzer claude-agent@pve, Token-ID z. B. homelab-mcp. Lass „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 brauchst beides weiter unten.

2. Sicherstellen, dass der Gast-Agent der Nettovermögensrechner-VM aktiviert ist

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

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

2. Installiere in der Windows-VM den Gast-Agent-Dienst, falls er nicht bereits 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“ ausgeführt wird.

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

(Schiebe dieses Repo zuerst auf GitHub und ersetze dann REPLACE_WITH_THIS_REPO_URL oben durch https://github.com/<you>/<repo> — GitHub erlaubt es nicht, dass der Button auf sich selbst verlinkt, bevor das Repo existiert.)

Wenn du auf den Button klickst, wird das Repo in Cloudflare Workers Builds geforkt/verbunden und das Deployment für dich ausgeführt. Nutzbar ist es aber noch nicht — siehe Schritt 4.

Manuelles Bereitstellen (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 dem Bereitstellen die Secrets setzen

Egal ob du den Button oder die CLI verwendet hast: Es werden drei Secrets benötigt, die absichtlich nicht in diesem Repo enthalten sind (sie stehen nicht in wrangler.jsonc, was in Ordnung ist, da die Datei öffentlich sein darf):

Setze sie im Cloudflare-Dashboard unter deinem Worker → Einstellungen → Variablen und Secrets → Hinzufügen → Verschlüsseln oder über npx wrangler secret put <NAME>.

Prü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 Variablen und 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 bei jeder Anfrage Authorization: Bearer <MCP_BEARER_TOKEN>, bevor er etwas tut — ohne ihn erhält jeder Tool-Aufruf eine 401. Falls deine Claude-Connector-Einrichtung das Anhängen eines benutzerdefinierten Headers/API-Schlüssels erlaubt, setze diesen Header dort. Falls nicht, gibt es zwei Optionen:

• Setzen Sie stattdessen eine Cloudflare Access-Richtlinie vor die Route des Workers (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 löschen Sie die Bearer-Token-Prüfung in src/index.ts (fetch(), Anfang der Funktion) und verlassen Sie sich darauf, dass die URL des Workers selbst unerratbar ist. Nicht empfohlen für alles, was mit Proxmox in Berührung kommen kann.

6. Ausprobieren

Sobald die Verbindung steht, sollten in einem Claude-Chat "liste die VMs auf drumfire03" oder "wie ist der Status von VM 107" echte Daten zurückgeben. Für den Nettovermögens-Workflow zieht Claude Daten aus Firefly III (bereits verbunden), erstellt das JSON, das der Rechner erwartet, und ruft update_networth_calculator mit diesem JSON als Zeichenkette auf.

Sobald das funktioniert, probieren Sie auch die neueren Tools aus — "prüfe den Zustand des Clusters", "wie ist die aktuelle IP von VM 107?", "klone VM-OnPremTest in eine Testkopie", "erhöhe diese VM auf 4 Kerne".

Hinweis zu Berechtigungen: Proxmox' genaue Berechtigungsanforderungen für Firewall-Regel- und einige Netzwerk-Lese-Endpunkte variieren je nach Version etwas, und die obige Rolle ist eine Best-Effort-Zuordnung, nicht gegen Ihre spezifische Proxmox-Version getestet. Wenn ein Toolaufruf mit einem 403 zurückkommt, enthält die Fehlermeldung Proxmox' tatsächliche Antwort — die Lösung ist fast immer das Hinzufügen einer weiteren Berechtigung zu ClaudeHomelabOps (üblicherweise nur die Bestätigung, dass Sys.Audit auf / angewendet wird, nicht nur auf einem Unterpfad).