Skip to main content
Glama
proxmox-mcp

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 --build

Por defecto, el servidor MCP escucha en:

http://127.0.0.1:8000/mcp

Configuración predeterminada de transporte MCP en .env.example:

MCP_TRANSPORT=streamable-http
MCP_PORT=8000
MCP_PATH=/mcp

Dentro 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 remotas

  • sse — transporte MCP HTTP/SSE heredado

  • stdio — 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 certs

Si intencionalmente necesita HTTP plano para Proxmox, hágalo explícito:

PVE_BASE_URL=http://proxmox.lan:8006
PVE_ALLOW_INSECURE_HTTP=true

HTTP 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-me

La 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-me

Configuración de Hermes para Docker HTTP MCP

mcp_servers:
  proxmox:
    url: "http://127.0.0.1:8000/mcp"
    timeout: 120
    connect_timeout: 30

Si se implementa en un host remoto detrás de TLS:

mcp_servers:
  proxmox:
    url: "https://proxmox-mcp.example.internal/mcp"
    timeout: 120
    connect_timeout: 30

Ejecució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-mcp

Modo HTTP local sin Docker:

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run proxmox-mcp

Modelo de seguridad

  • Las solicitudes GET están permitidas por defecto.

  • POST, PUT y DELETE requieren confirm=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_version

  • pve_get_cluster_status

  • pve_list_nodes

  • pve_list_resources

  • pve_list_vms

  • pve_get_vm_status

  • pve_get_vm_config

  • pve_list_storage

  • pve_list_backups

  • pve_get_task_status

  • pve_get_node_metrics

Fase 2: Acciones seguras

  • pve_start_vm

  • pve_shutdown_vm

  • pve_stop_vm

  • pve_reboot_vm

  • pve_suspend_vm

  • pve_resume_vm

  • pve_create_snapshot

  • pve_delete_snapshot

  • pve_rollback_snapshot

  • pve_migrate_vm

Fase 3: Administración/aprovisionamiento + vía de escape

  • pve_clone_vm

  • pve_create_lxc

  • pve_create_qemu_vm

  • pve_delete_vm

  • pve_resize_disk

  • pve_set_vm_config

  • pve_api_request

Desarrollo

uv sync --extra dev
uv run pytest
uv run ruff check .

Available Tools

28 tools
pve_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

    B3.1/5.0

    Scored across 28 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An 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 npm
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      An 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.
      20
      MIT