proxmox-ai

MCP-Server, der es einem KI-Agenten ermöglicht, Proxmox VE in natürlicher Sprache zu verwalten, ohne ihm jemals mehr Macht zu geben als unbedingt nötig.

"¿Qué contenedores están ejecutándose?"        → responde
"¿Cuál está consumiendo más RAM?"              → responde
"Reinicia el CT 105"                           → propone, espera confirmación, ejecuta
"Haz rollback del snapshot pre-update"         → exige una frase literal del humano
"Borra el CT 105"                              → no existe esa herramienta

Das Design geht von einer Idee aus: das Modell schlägt vor, die Policy-Engine entscheidet und das Audit-Log erinnert sich.

Status

Phase 1 (nur Lesen) ist implementiert und getestet. Die Phasen 2 bis 5 sind implementiert, aber standardmäßig deaktiviert: Sie werden einzeln über Umgebungsvariablen aktiviert, und jede benötigt zusätzlich ihr Privileg in der Proxmox-ACL. Siehe docs/roadmap.md.

Schnellinstallation

Erstelle auf dem Proxmox-Knoten den dedizierten Benutzer und das Token:

./scripts/setup-proxmox-user.sh

Kopiere das Token-Geheimnis: Proxmox zeigt es nicht noch einmal an.

In dem Container, in dem der MCP leben wird (siehe docs/instalacion.md zur Erstellung):

git clone https://github.com/dallaswk/proxmox-ai.git
cd proxmox-ai
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env && chmod 600 .env
$EDITOR .env          # PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET

Überprüfe, dass er startet und die Infrastruktur sieht:

set -a && . ./.env && set +a
proxmox-ai            # habla MCP por stdin/stdout; Ctrl-C para salir

Verbinde ihn mit deinem MCP-Client (Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "proxmox": {
      "command": "/opt/proxmox-ai/.venv/bin/proxmox-ai",
      "env": {
        "PROXMOX_HOST": "proxmox.midominio.local",
        "PROXMOX_TOKEN_ID": "ai-agent@pve!mcp",
        "PROXMOX_TOKEN_SECRET": "...",
        "PROXMOX_AI_READ_ONLY": "true",
        "PROXMOX_AI_AUDIT_LOG": "/var/log/proxmox-ai/audit.jsonl"
      }
    }
  }
}

Wie die Sicherheit funktioniert

Vier unabhängige Schichten. Jede für sich ist wirksam:

1. Die Proxmox-ACL. Sie ist die eigentliche Grenze. Das Token ist ein dedizierter Benutzer mit --privsep 1, niemals root@pam, und in Phase 1 hat es nur PVEAuditor. Ein Token, das eine VM nicht löschen kann, löscht sie nicht, selbst wenn alles andere versagt.

2. Capability-Flags. PROXMOX_AI_READ_ONLY=true blockiert jede Schreiboperation, unabhängig von der restlichen Konfiguration. Jede Phase hat ihr eigenes Flag, und irreversible Operationen benötigen ein zusätzliches.

3. Zweistufige Bestätigung. Ein Schreibwerkzeug, das ohne confirm_token aufgerufen wird, fasst nichts an: Es gibt einen Plan und ein Einmal-Token zurück, das an genau diese Aktion gebunden ist. Der Mensch sieht den Plan zwischen den beiden Aufrufen. Für irreversible Operationen muss zusätzlich ein wörtlicher Satz gesendet werden (CONFIRMO ROLLBACK SNAPSHOT 105); ein „Ja" reicht nicht.

4. Keine beliebige Shell. Es gibt kein execute_any_command. Die Befehle in den Guests durchlaufen eine Whitelist für argv, mit zwei Blacklists davor – Binärdateien (rm, dd, bash…) und destruktive Optionen – sowie Ablehnung von Shell-Metazeichen. Die Options-Blacklist existiert, weil ein Binärprogramm, das wie ein Lese-Tool aussieht, ein Flag haben kann, das es nicht ist: journalctl -u nginx --vacuum-time=1s löscht die archivierten Logs. Die Argumente werden zusätzlich mit shlex.quote escaped, weil ssh host cmd immer von der entfernten Shell neu interpretiert wird.

Und darunter liegt ein append-only JSONL-Log mit jedem Versuch – einschließlich der abgelehnten – und ohne ein einziges Geheimnis.

Was das nicht löst: Ein MCP-Server kann nicht unterscheiden zwischen „der Mensch hat ja gesagt" und „das Modell hat beschlossen, weiterzumachen". Die zweistufige Bestätigung garantiert, dass nichts Irreversibles als Nebeneffekt eines einzelnen Aufrufs passiert, und hinterlässt Spuren von allem, aber die dauerhafte Garantie ist die ACL. Das ist ohne Schnörkel erklärt in docs/modelo-de-seguridad.md.

Werkzeuge

Phase 1 – Lesen (standardmäßig aktiv, benötigt nur PVEAuditor)

Phase 2 – Stromversorgung (PROXMOX_AI_ENABLE_POWER, Berechtigung VM.PowerMgmt)

pve_guest_power – start, shutdown, reboot, stop. Bestätigung erforderlich.

Phase 3 – Snapshots (PROXMOX_AI_ENABLE_SNAPSHOT, Berechtigung VM.Snapshot)

pve_create_snapshot (Stufe 1) · pve_rollback_snapshot und pve_delete_snapshot (Stufe 2: wörtlicher Satz + PROXMOX_AI_ENABLE_DESTRUCTIVE)

Phase 4 – Backups (PROXMOX_AI_ENABLE_BACKUP, Berechtigung VM.Backup)

pve_create_backup – Stufe 1. Die Wiederherstellung ist absichtlich nicht implementiert: Sie ist die destruktivste Operation in Proxmox. Siehe docs/modelo-de-seguridad.md.

Phase 5 – Diagnose innerhalb der Guests (PROXMOX_AI_ENABLE_GUEST_EXEC)

Reales Beispiel der zweistufigen Bestätigung

Usuario:  Reinicia el CT 105.

Agente:   [pve_guest_power vmid=105 operation=reboot]
          → confirmation_required
            "REBOOT CT 105 (web-production) on node pve1 — will request a
             clean reboot via the guest OS."
            nothing_has_changed: true
            confirm_token: "kJ8x...b2"

          Voy a reiniciar el CT 105 (web-production) en el nodo pve1.
          Es un reinicio limpio a través del sistema operativo. ¿Confirmas?

Usuario:  Sí.

Agente:   [pve_guest_power vmid=105 operation=reboot confirm_token="kJ8x...b2"]
          → status: completed

          Reiniciado. La tarea terminó con estado OK.

Wenn der Agent dasselbe Token für den CT 101 oder für ein stop statt eines reboot verwenden würde, würde die Engine es ablehnen: Das Token ist per HMAC an die genaue Aktion, den Guest und die Parameter gebunden.

Entwicklung

pip install -e ".[dev]"
pytest                    # 229 tests, sin red ni Proxmox real
ruff check src tests

Die Tests verwenden httpx.MockTransport mit einem Fake-Cluster (1 Knoten, 2 CT, 1 VM, 2 Storages). Für die Entwicklung ist kein Proxmox erforderlich.

Dokumentation

• docs/instalacion.md – Schritt-für-Schritt-Installation

• docs/modelo-de-seguridad.md – Bedrohungen und Grenzen

• docs/roadmap.md – die 7 Phasen, mit Checkliste

• docs/especificacion-original.md – das Ausgangsdokument

Lizenz

MIT