Proxmox-mcp

Name: proxmox-mcp
Author: akmalovaa

Release License: MIT Python 3.14 GHCR MCP

Einfaches Proxmox MCP

MCP-Server zur Verwaltung von Proxmox VE

38 Tools — Nodes, QEMU-VMs, LXC-Container, Speicher, Cluster, Snapshots.

Warum dieses hier?

Ein Image, Multi-Architektur — docker run ghcr.io/akmalovaa/proxmox-mcp:latest und fertig
Nur Umgebungsvariablen — keine Konfigurationsdateien, keine Datenbank, kein Status
Standardmäßig schreibgeschützt — destruktive Vorgänge sind durch ein explizites PROXMOX_RISK_LEVEL geschützt
Kleine Codebasis — reines stdio-MCP über Proxmoxer, kein HTTP-Server, keine Authentifizierungsebene, kein Schnickschnack
Rohe JSON-Ausgabe — keine Formatierung, keine Emojis; das LLM erhält saubere Daten

Schnellstart

Image: ghcr.io/akmalovaa/proxmox-mcp:latest (Multi-Architektur: amd64 + arm64).

1. Exportieren Sie die Anmeldedaten in Ihrem Shell-Profil (~/.zprofile, ~/.zshrc oder ~/.bashrc):

# base environment:
export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_PASSWORD=your-password

# or use token auth (recommended):
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# optional:
export PROXMOX_RISK_LEVEL=read

Neu laden: source ~/.zprofile (oder Shell neu starten).

2. Hinzufügen zu ~/.claude/settings.json (Claude Code) oder claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_PASSWORD",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

oder Token-Authentifizierung:

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_TOKEN_NAME",
        "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

docker run -e VAR ohne Wert leitet die Host-Variable durch — keine Geheimnisse in der Konfigurationsdatei. Starten Sie den Client neu — 38 Proxmox-Tools werden verfügbar.

Für die Passwort-Authentifizierung tauschen Sie die Token-Variablen gegen PROXMOX_PASSWORD aus.

Hinweis: Claude Desktop unter macOS wird über launchd gestartet und erbt nicht ~/.zprofile/~/.zshrc. Fügen Sie die Exporte entweder in ~/.zshenv ein oder greifen Sie auf einen Inline-"env": { ... }-Block in der Konfiguration zurück.

Konfiguration

Alle Einstellungen sind Umgebungsvariablen — legen Sie diese in Ihrem Shell-Profil fest, übergeben Sie sie inline an docker run -e oder deklarieren Sie sie im env-Block Ihres MCP-Clients.

Variable	Standard	Beschreibung
`PROXMOX_HOST`	—	Proxmox-Host (IP oder Hostname)
`PROXMOX_USER`	`root@pam`	API-Benutzer
Auth	—
`PROXMOX_PORT`	`8006`	API-Port
`PROXMOX_VERIFY_SSL`	`false`	TLS-Zertifikat verifizieren
`PROXMOX_RISK_LEVEL`	`read`	`read` / `lifecycle` / `all`

Authentifizierung: Token oder Passwort

Wählen Sie eines aus. Wenn beide gesetzt sind, hat das Token Vorrang.

Token (empfohlen) — Erstellung in der Proxmox-Benutzeroberfläche: Datacenter → Permissions → API Tokens → Add (deaktivieren Sie Privilege Separation). Dann:

export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Passwort (Fallback):

export PROXMOX_PASSWORD=your-password

Risikostufen

PROXMOX_RISK_LEVEL schützt destruktive Vorgänge:

Stufe	Fügt hinzu
`read` (Standard)	schreibgeschützte Tools
`lifecycle`	+ start / stop / reboot / suspend / clone / create-snapshot
`all`	+ delete-snapshot / rollback-snapshot

Jeder privilegierte Aufruf wird in stderr protokolliert (ALLOW / DENY + Tool + Stufe).

Tools

Nodes (7)

Tool	Beschreibung
`list_nodes`	Alle Cluster-Nodes mit Status, CPU, Arbeitsspeicher, Betriebszeit auflisten
`get_node_status`	Detaillierte Node-Metriken (CPU, Arbeitsspeicher, Festplatte, Auslastung, Kernel)
`get_node_networks`	Netzwerkschnittstellen auf einem Node
`get_node_disks`	Physische Festplatten auf einem Node
`get_node_tasks`	Kürzliche Aufgaben auf einem Node
`get_task_status`	Status einer bestimmten Aufgabe nach UPID
`get_task_log`	Protokollausgabe einer Aufgabe

QEMU-VMs (14)

Tool	Stufe	Beschreibung
`list_vms`	read	Alle VMs auflisten, optional nach Node filtern
`get_vm_status`	read	Aktueller VM-Status (läuft/gestoppt, CPU, Arbeitsspeicher)
`get_vm_config`	read	VM-Konfiguration (Hardware, Festplatten, Netzwerk)
`list_vm_snapshots`	read	Alle Snapshots einer VM auflisten
`start_vm`	lifecycle	Eine VM starten
`stop_vm`	lifecycle	Eine VM zwangsweise stoppen
`shutdown_vm`	lifecycle	Sanftes ACPI-Herunterfahren mit Timeout
`reboot_vm`	lifecycle	Neustart über ACPI
`suspend_vm`	lifecycle	Eine VM anhalten
`resume_vm`	lifecycle	Eine angehaltene VM fortsetzen
`clone_vm`	lifecycle	Vollständiger oder verknüpfter Klon
`create_vm_snapshot`	lifecycle	Einen Snapshot erstellen
`delete_vm_snapshot`	all	Einen Snapshot löschen
`rollback_vm_snapshot`	all	Auf einen Snapshot zurücksetzen

LXC-Container (11)

Tool	Stufe	Beschreibung
`list_containers`	read	Alle LXC-Container auflisten, optional nach Node filtern
`get_container_status`	read	Aktueller Container-Status
`get_container_config`	read	Container-Konfiguration
`list_container_snapshots`	read	Alle Snapshots auflisten
`start_container`	lifecycle	Einen Container starten
`stop_container`	lifecycle	Einen Container zwangsweise stoppen
`shutdown_container`	lifecycle	Sanftes Herunterfahren mit Timeout
`reboot_container`	lifecycle	Einen Container neu starten
`create_container_snapshot`	lifecycle	Einen Snapshot erstellen
`delete_container_snapshot`	all	Einen Snapshot löschen
`rollback_container_snapshot`	all	Auf einen Snapshot zurücksetzen

Speicher (2)

Tool	Beschreibung
`list_storage`	Speicherpools mit Auslastung, optional nach Node filtern
`get_storage_content`	Inhalte eines Speicherpools (ISOs, Backups, Images, Vorlagen)

Cluster (4)

Tool	Beschreibung
`get_cluster_status`	Cluster-Integrität, Quorum, Node-Mitgliedschaft
`get_cluster_resources`	Alle Ressourcen (VMs, Container, Speicher, Nodes)
`get_cluster_backups`	Konfigurierte Backup-Jobs
`get_next_vmid`	Nächste verfügbare VM/Container-ID

Architektur

src/proxmox_mcp/
├── server.py    # FastMCP instance + entry point
├── config.py    # Pydantic Settings (PROXMOX_ prefix)
├── client.py    # Proxmoxer connection via lifespan
└── tools/       # nodes, vms, containers, storage, cluster

Standardmäßig schreibgeschützt — privilegierte Tools durch PROXMOX_RISK_LEVEL geschützt
Einzelne Verbindung — Proxmoxer-Client wird einmal beim Start erstellt und über die Lebensdauer geteilt
Rohe JSON-Ausgabe — keine Formatierung; das LLM verarbeitet die Daten direkt

Entwicklung

Standalone ausführen (Testen)

export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

docker run -i --rm \
  -e PROXMOX_HOST -e PROXMOX_USER \
  -e PROXMOX_TOKEN_NAME -e PROXMOX_TOKEN_VALUE \
  ghcr.io/akmalovaa/proxmox-mcp:latest

Ohne Docker (UV)

git clone https://github.com/akmalovaa/proxmox-mcp.git && cd proxmox-mcp && uv sync

MCP-Client-Konfiguration:

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "proxmox-mcp"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_NAME": "mcp",
        "PROXMOX_TOKEN_VALUE": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Aus Quellcode bauen

git clone https://github.com/akmalovaa/proxmox-mcp.git
cd proxmox-mcp
docker build -t proxmox-mcp .

Lizenz

MIT

proxmox-mcp

Proxmox-mcp

Warum dieses hier?

Schnellstart

Konfiguration

Authentifizierung: Token oder Passwort

Risikostufen

Tools

Nodes (7)

QEMU-VMs (14)

LXC-Container (11)

Speicher (2)

Cluster (4)

Architektur

Entwicklung

Standalone ausführen (Testen)

Ohne Docker (UV)

Aus Quellcode bauen

Lizenz

Maintenance

Resources

Tools

Latest Blog Posts

MCP directory API