proxmox-mcp
proxmox-mcp
Un servidor de Protocolo de Contexto de Modelo (MCP) diseñado principalmente para Docker para Proxmox VE.
Expone herramientas estructuradas y seguras para la inspección de clústeres en modo de solo lectura, operaciones de ciclo de vida de máquinas virtuales/contenedores, instantáneas, migración, asistentes de aprovisionamiento y una vía de escape protegida para la API genérica de Proxmox.
Estado
Alfa. Construido con autenticación mediante token de API y puertas de confirmación explícitas para operaciones de mutación.
Related MCP server: Proxmox MCP Server
Ejecución con Docker Compose
Docker Compose es la forma principal admitida para ejecutar este servidor MCP.
cp .env.example .env
# edit .env with your Proxmox URL and token
docker compose up -d --buildPor defecto, el servidor MCP escucha en:
http://127.0.0.1:8000/mcpConfiguración predeterminada de transporte MCP en .env.example:
MCP_TRANSPORT=streamable-http
MCP_PORT=8000
MCP_PATH=/mcpDentro de Docker, la aplicación se vincula a 0.0.0.0 en el contenedor, pero Compose lo publica solo en el loopback del host por defecto:
ports:
- "127.0.0.1:8000:8000"No publique este endpoint MCP sin autenticación en todas las interfaces a menos que coloque controles de red reales frente a él.
Transportes MCP admitidos:
streamable-http— predeterminado para Docker y la mayoría de las implementaciones remotassse— transporte MCP HTTP/SSE heredadostdio— modo de subproceso local
Para la exposición HTTPS del endpoint MCP, coloque este servicio detrás de un proxy inverso como Caddy, Traefik o nginx y termine TLS allí. Mantenga el contenedor en HTTP plano internamente a menos que tenga una razón específica para hacer lo contrario.
Configuración del protocolo Proxmox
Prefiera HTTPS para la API de Proxmox:
PVE_BASE_URL=https://proxmox.lan:8006
PVE_VERIFY_SSL=false # only for self-signed homelab certsSi intencionalmente necesita HTTP plano para Proxmox, hágalo explícito:
PVE_BASE_URL=http://proxmox.lan:8006
PVE_ALLOW_INSECURE_HTTP=trueHTTP plano envía credenciales a través de la red. Eso suele ser una mala idea fuera de una red de laboratorio estrictamente controlada.
Autenticación
Prefiera un token de API de Proxmox:
PVE_API_TOKEN_ID=user@pam!token-name
PVE_API_TOKEN_SECRET=replace-meLa autenticación mediante ticket de contraseña también es compatible, pero los tokens de API son más limpios para MCP:
PVE_USERNAME=user@pam
PVE_PASSWORD=replace-meConfiguración de Hermes para Docker HTTP MCP
mcp_servers:
proxmox:
url: "http://127.0.0.1:8000/mcp"
timeout: 120
connect_timeout: 30Si se implementa en un host remoto detrás de TLS:
mcp_servers:
proxmox:
url: "https://proxmox-mcp.example.internal/mcp"
timeout: 120
connect_timeout: 30Ejecución sin Docker
El modo stdio local sigue estando disponible para el desarrollo:
MCP_TRANSPORT=stdio uvx proxmox-mcp
# or from a checkout:
MCP_TRANSPORT=stdio uv run proxmox-mcpModo HTTP local sin Docker:
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run proxmox-mcpModelo de seguridad
Las solicitudes
GETestán permitidas por defecto.POST,PUTyDELETErequierenconfirm=true.Las herramientas de ciclo de vida/aprovisionamiento de alto nivel también requieren
confirm=true.Los secretos nunca se devuelven intencionalmente.
Las rutas de API genéricas rechazan URLs completas, cadenas de consulta, fragmentos, recorridos, recorridos codificados y trucos de barra diagonal codificada.
Los segmentos de ruta se validan y codifican antes de enviarse a Proxmox.
Cobertura de herramientas
Fase 1: Solo lectura
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
Fase 2: Acciones seguras
pve_start_vmpve_shutdown_vmpve_stop_vmpve_reboot_vmpve_suspend_vmpve_resume_vmpve_create_snapshotpve_delete_snapshotpve_rollback_snapshotpve_migrate_vm
Fase 3: Administración/aprovisionamiento + vía de escape
pve_clone_vmpve_create_lxcpve_create_qemu_vmpve_delete_vmpve_resize_diskpve_set_vm_configpve_api_request
Desarrollo
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