proxmox-mcp
proxmox-mcp
Ein Docker-basierter Model Context Protocol (MCP) Server für Proxmox VE.
Er stellt sichere, strukturierte Werkzeuge für die schreibgeschützte Cluster-Inspektion, VM-/Container-Lebenszyklusoperationen, Snapshots, Migration, Bereitstellungshilfen und einen geschützten, generischen Proxmox-API-Ausgang bereit.
Status
Alpha. Entwickelt mit API-Token-Authentifizierung und expliziten Bestätigungsgates für mutierende Operationen.
Related MCP server: Proxmox MCP Server
Ausführung mit Docker Compose
Docker Compose ist die primär unterstützte Methode, um diesen MCP-Server auszuführen.
cp .env.example .env
# edit .env with your Proxmox URL and token
docker compose up -d --buildStandardmäßig lauscht der MCP-Server auf:
http://127.0.0.1:8000/mcpStandard-MCP-Transporteinstellungen in .env.example:
MCP_TRANSPORT=streamable-http
MCP_PORT=8000
MCP_PATH=/mcpInnerhalb von Docker bindet sich die App an 0.0.0.0 im Container, aber Compose veröffentlicht sie standardmäßig nur auf dem Host-Loopback:
ports:
- "127.0.0.1:8000:8000"Veröffentlichen Sie diesen nicht authentifizierten MCP-Endpunkt nicht auf allen Schnittstellen, es sei denn, Sie haben echte Netzwerkkontrollen davor geschaltet.
Unterstützte MCP-Transporte:
streamable-http— Standard für Docker und die meisten Remote-Bereitstellungensse— Legacy HTTP/SSE MCP-Transportstdio— lokaler Subprozess-Modus
Für die HTTPS-Bereitstellung des MCP-Endpunkts platzieren Sie diesen Dienst hinter einem Reverse Proxy wie Caddy, Traefik oder nginx und beenden Sie TLS dort. Behalten Sie den Container intern auf einfachem HTTP, es sei denn, Sie haben einen spezifischen Grund, dies anders zu handhaben.
Proxmox-Protokollkonfiguration
Bevorzugen Sie HTTPS für die Proxmox-API:
PVE_BASE_URL=https://proxmox.lan:8006
PVE_VERIFY_SSL=false # only for self-signed homelab certsWenn Sie absichtlich einfaches HTTP für Proxmox benötigen, machen Sie dies explizit:
PVE_BASE_URL=http://proxmox.lan:8006
PVE_ALLOW_INSECURE_HTTP=trueEinfaches HTTP sendet Anmeldeinformationen über das Netzwerk. Das ist normalerweise eine schlechte Idee außerhalb eines streng kontrollierten Labornetzwerks.
Authentifizierung
Bevorzugen Sie ein Proxmox-API-Token:
PVE_API_TOKEN_ID=user@pam!token-name
PVE_API_TOKEN_SECRET=replace-mePasswort-Ticket-Authentifizierung wird ebenfalls unterstützt, aber API-Token sind sauberer für MCP:
PVE_USERNAME=user@pam
PVE_PASSWORD=replace-meHermes-Konfiguration für Docker HTTP MCP
mcp_servers:
proxmox:
url: "http://127.0.0.1:8000/mcp"
timeout: 120
connect_timeout: 30Bei Bereitstellung auf einem Remote-Host hinter TLS:
mcp_servers:
proxmox:
url: "https://proxmox-mcp.example.internal/mcp"
timeout: 120
connect_timeout: 30Ausführung ohne Docker
Der lokale stdio-Modus bleibt für die Entwicklung verfügbar:
MCP_TRANSPORT=stdio uvx proxmox-mcp
# or from a checkout:
MCP_TRANSPORT=stdio uv run proxmox-mcpLokaler HTTP-Modus ohne Docker:
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run proxmox-mcpSicherheitsmodell
GET-Anfragen sind standardmäßig erlaubt.POST,PUTundDELETEerfordernconfirm=true.Hochrangige Lebenszyklus-/Bereitstellungswerkzeuge erfordern ebenfalls
confirm=true.Geheimnisse werden niemals absichtlich zurückgegeben.
Generische API-Pfade lehnen vollständige URLs, Abfragezeichenfolgen, Fragmente, Traversierung, kodierte Traversierung und kodierte Slash-Tricks ab.
Pfadsegmente werden validiert und kodiert, bevor sie an Proxmox gesendet werden.
Werkzeugabdeckung
Phase 1: Schreibgeschützt
pve_get_versionpve_get_cluster_statuspve_list_nodespve_list_resourcespve_list_vmspve_get_vm_statuspve_get_vm_configpve_list_storagepve_list_backupspve_get_task_statuspve_get_node_metrics
Phase 2: Sichere Aktionen
pve_start_vmpve_shutdown_vmpve_stop_vmpve_reboot_vmpve_suspend_vmpve_resume_vmpve_create_snapshotpve_delete_snapshotpve_rollback_snapshotpve_migrate_vm
Phase 3: Admin/Bereitstellung + Ausgang
pve_clone_vmpve_create_lxcpve_create_qemu_vmpve_delete_vmpve_resize_diskpve_set_vm_configpve_api_request
Entwicklung
uv sync --extra dev
uv run pytest
uv run ruff check .Available Tools
28 toolspve_api_requestC
Call any Proxmox API path. GET is allowed; POST/PUT/DELETE require confirm=true.
Inputs: path (required), method (required), params, confirm. Returns: object
pve_clone_vmC
Clone a QEMU VM. Requires confirm=true.
Inputs: node (required), newid (required), source_vmid (required), full, +4 more. Returns: object
pve_create_lxcC
Create an LXC container. Requires confirm=true.
Inputs: node (required), vmid (required), storage (required), ostemplate (required), +8 more. Returns: object
pve_create_qemu_vmC
Create a QEMU VM. Requires confirm=true.
Inputs: node (required), vmid (required), ide2, name, +7 more. Returns: object
pve_create_snapshotB
Create a VM/container snapshot. Requires confirm=true.
Inputs: node (required), vmid (required), snapname (required), confirm, +3 more. Returns: object
pve_delete_snapshotA
Delete a VM/container snapshot. Requires confirm=true.
Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object
pve_delete_vmC
Delete a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), purge, confirm, +2 more. Returns: object
pve_get_cluster_statusA
Return Proxmox cluster status.
Inputs: no named parameters. Returns: object
pve_get_node_metricsC
Get node status and metrics.
Inputs: node (required). Returns: object
pve_get_task_statusC
Get task status by UPID.
Inputs: node (required), upid (required). Returns: object
pve_get_versionA
Return Proxmox VE version information.
Inputs: no named parameters. Returns: object
pve_get_vm_configA
Get config for a QEMU VM or LXC container.
Inputs: node (required), vmid (required), vm_type. Returns: object
pve_get_vm_statusB
Get current status for a QEMU VM or LXC container.
Inputs: node (required), vmid (required), vm_type. Returns: object
pve_list_backupsB
List backup content for a node storage.
Inputs: node (required), storage (required). Returns: object
pve_list_nodesA
List Proxmox nodes.
Inputs: no named parameters. Returns: object
pve_list_resourcesB
List cluster resources, optionally filtered by type such as vm, storage, node.
Inputs: resource_type. Returns: object
pve_list_storageA
List storage globally or for a node.
Inputs: node. Returns: object
pve_list_vmsA
List QEMU VMs and LXC containers from cluster resources.
Inputs: no named parameters. Returns: object
pve_migrate_vmB
Migrate a VM/container to another node. Requires confirm=true.
Inputs: node (required), vmid (required), target (required), online, +4 more. Returns: object
pve_reboot_vmA
Reboot a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
pve_resize_diskC
Resize a QEMU VM disk. Requires confirm=true.
Inputs: disk (required), node (required), size (required), vmid (required), +1 more. Returns: object
pve_resume_vmB
Resume a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
pve_rollback_snapshotC
Rollback to a snapshot. Requires confirm=true.
Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object
pve_set_vm_configC
Update VM/container config. Requires confirm=true.
Inputs: node (required), vmid (required), config (required), confirm, +1 more. Returns: object
pve_shutdown_vmB
Gracefully shut down a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, timeout, +2 more. Returns: object
pve_start_vmC
Start a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
pve_stop_vmA
Hard stop a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
pve_suspend_vmC
Suspend a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools target a distinct resource/action combination, and lifecycle verbs like start, shutdown, stop, and reboot are clear. The main ambiguity comes from the overlapping read-only listing tools (list_resources, list_vms, list_nodes, list_storage), though the descriptions help differentiate them. pve_api_request is a deliberate escape hatch rather than a source of confusion.
All tools follow a consistent pve_verb_noun snake_case pattern. Verbs are predictable: list/get for reads, create/delete/set for mutations, and explicit lifecycle verbs for VM/container actions. There are no mixed naming conventions or vague generic names.
28 tools exceeds the 25+ threshold and feels heavy for a single server. Several listing and config tools could be consolidated, and the generic pve_api_request already provides broad fallback coverage. The domain is broad but the surface is larger than necessary.
Core VM/container lifecycle, snapshot management, migration, cloning, creation, deletion, config updates, and disk resize are covered. Notable gaps like LXC clone/resize and advanced storage/network management are not directly exposed, but pve_api_request provides a workaround. The surface has no critical dead ends.
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for Product Management
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn open-source MCP server for managing Proxmox environments, including nodes, virtual machines, and containers. It enables users to perform inventory checks, status monitoring, and control operations directly through MCP-compatible tools.109 npm2MIT
- AlicenseCqualityCmaintenanceA comprehensive MCP server providing 92 tools for managing Proxmox Virtual Environment, including QEMU VMs and LXC containers.92190 npm6MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for full Proxmox VE management - VMs, containers, storage, backups, networking.2MIT
- AlicenseBqualityCmaintenanceAn MCP server that exposes Proxmox VE node/cluster as tools for MCP clients, enabling management of VMs and containers including power control, resource reconfiguration, snapshots, and backups.20MIT