ProxmoxMCP-Plus

Servidor MCP de Proxmox VE para VMs, LXCs, instantáneas, copias de seguridad, almacenamiento y operaciones de clúster.

Documentación

ProxmoxMCP-Plus

Opera Proxmox VE desde clientes MCP, agentes de IA y herramientas OpenAPI a través de un plano de control consciente de la seguridad para VMs, LXCs, snapshots, copias de seguridad, ISOs, comandos de contenedores y trabajos persistentes de larga duración.

ProxmoxMCP-Plus architecture

Por qué ProxmoxMCP-Plus

ProxmoxMCP-Plus se sitúa entre los clientes de IA y Proxmox VE para que los operadores no tengan que ensamblar llamadas API crudas, scripts de shell puntuales y sondeos de trabajos personalizados para cada flujo de trabajo.

Expone la misma superficie operativa de dos maneras:

MCP para Claude Desktop, Cursor, VS Code, Open WebUI, Codex y otros agentes compatibles con MCP
OpenAPI para automatización HTTP, paneles de control, herramientas internas y flujos de trabajo sin código

Lo que obtienes:

Acciones del ciclo de vida de VM y LXC
Creación, reversión y eliminación de snapshots
Flujos de trabajo de copia de seguridad y restauración
Descarga y limpieza de ISOs
Inspección de nodos, almacenamiento y clúster
Ejecución de comandos en contenedores respaldada por SSH con salvaguardas
Seguimiento persistente de trabajos para tareas asíncronas de Proxmox

Qué Lo Hace Diferente

Prioridad	Cómo lo maneja el proyecto
Rutas de acceso duales	MCP nativo para flujos de trabajo de agentes y OpenAPI para automatización HTTP estándar
Flujos de trabajo orientados a Proxmox	Operaciones de día 2 para VM, LXC, snapshot, copia de seguridad, ISO, almacenamiento y clúster
Operaciones de larga duración	`job_id`s estables, seguimiento de `UPID` de Proxmox, sondeo, reintento, cancelación e historial de auditoría
Ejecución más segura	Tokens de API de Proxmox, autenticación bearer de OpenAPI, política de comandos, tokens de aprobación, validación TLS y controles de Host/Origin de MCP HTTP
Validación real	Los puntos de entrada de pruebas unitarias, de integración, Docker/OpenAPI y e2e en vivo de Proxmox están documentados en el repositorio

Inicio Rápido

1. Preparar Credenciales de Proxmox

Crea un token de API de Proxmox con solo los permisos que tus flujos de trabajo necesiten. Luego crea el archivo de configuración local:

cp proxmox-config/config.example.json proxmox-config/config.json

Luego edita proxmox-config/config.json con tu entorno. Como mínimo, necesita:

proxmox.host
proxmox.port
auth.user
auth.token_name
auth.token_value

Agrega también una sección ssh si deseas ejecución de comandos en contenedores. Agrega una sección jobs si deseas que el estado de los trabajos se persista en un lugar distinto al archivo SQLite local predeterminado.

Para verificación real en vivo, usa un proxmox-config/config.live.json separado creado desde proxmox-config/config.live.example.json. No apuntes las pruebas e2e en vivo a un config.json de marcador de posición o solo local a menos que ejecutes intencionalmente un túnel API local allí.

Configuración opcional de persistencia de trabajos:

{
  "jobs": {
    "sqlite_path": "proxmox-jobs.sqlite3"
  }
}

El filtrado opcional de exposición de herramientas puede reducir los esquemas enviados a los clientes MCP. Está deshabilitado por defecto, por lo que las configuraciones existentes continúan exponiendo cada herramienta disponible. Configura exactamente un modo bajo mcp:

{
  "mcp": {
    "tool_allowlist": ["get_nodes", "get_vms", "get_containers", "get_storage"]
  }
}

Alternativamente, usa tool_denylist, o las variables de entorno separadas por comas MCP_TOOL_ALLOWLIST y MCP_TOOL_DENYLIST. No configures ambos modos. La selección de entorno reemplaza el modo de filtrado a nivel de archivo. Una lista de permitidos vacía no expone herramientas; una lista de denegados vacía no oculta ninguna. Se requieren nombres de herramientas exactos en minúsculas, y los nombres desconocidos fallan al inicio para que un error tipográfico no pueda ampliar silenciosamente el acceso. Reinicia o reconecta el servidor MCP después de cambiar el filtro.

2. Elige Una Ruta de Ejecución

Ruta	Mejor para	Comando de inicio	Verificar
MCP stdio desde PyPI	Claude Desktop, Cursor, VS Code, Codex, agentes locales	`uvx proxmox-mcp-plus`	el cliente lista `get_nodes`, `get_vms` y herramientas de trabajos
MCP HTTP nativo desde Docker	clientes MCP remotos que soportan Streamable HTTP	`docker compose --profile mcp-http up -d proxmox-mcp-http`	conectar a `http://localhost:8000/mcp`
Puente OpenAPI desde Docker	clientes HTTP, paneles, scripts, herramientas sin código	`docker compose up -d`	`curl -f http://localhost:8811/livez`

MCP stdio con PyPI

uvx proxmox-mcp-plus

O instálalo primero:

pip install proxmox-mcp-plus
proxmox-mcp-plus

Usa esta ruta cuando el cliente MCP inicie un servidor stdio local.

MCP HTTP nativo con Docker

Usa esta ruta cuando un cliente MCP remoto soporte Streamable HTTP:

export MCP_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 8000:8000 \
  -e PROXMOX_MCP_MODE=mcp-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_TRANSPORT=STREAMABLE_HTTP \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Apunta los clientes MCP a:

http://<docker-host>:8000/mcp

Envía Authorization: Bearer <MCP_API_KEY> con cada solicitud MCP HTTP. MCP_API_KEY está deliberadamente separado del PROXMOX_API_KEY solo de OpenAPI, para que las dos superficies puedan rotarse de forma independiente. Si MCP_API_KEY no está configurado, Streamable HTTP permanece sin autenticación por compatibilidad hacia atrás y registra una advertencia de seguridad al inicio.

Al servir MCP HTTP detrás de un proxy inverso, mantén habilitada la protección contra rebinding de DNS y permite solo los nombres de host que esperas:

docker run --rm -p 8000:8000 \
  -e PROXMOX_MCP_MODE=mcp-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e MCP_TRANSPORT=STREAMABLE_HTTP \
  -e MCP_API_KEY="$MCP_API_KEY" \
  -e MCP_DNS_REBINDING_PROTECTION=true \
  -e MCP_ALLOWED_HOSTS=mcp.example.com:*,localhost:* \
  -e MCP_ALLOWED_ORIGINS=https://mcp.example.com \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Puente OpenAPI con Docker

El modo OpenAPI es el runtime Docker predeterminado y requiere una clave API:

export PROXMOX_API_KEY="$(openssl rand -hex 32)"
docker run --rm -p 8811:8811 \
  -e PROXMOX_API_KEY="$PROXMOX_API_KEY" \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Verifica la superficie OpenAPI:

curl -f http://localhost:8811/livez
curl -f -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/health
curl -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/openapi.json

Para desarrollo local sin autenticación únicamente, configura PROXMOX_ALLOW_NO_AUTH=true.

Checkout del código fuente

git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
cd ProxmoxMCP-Plus
uv venv
uv pip install -e ".[dev]"
python main.py

El servicio 8811 es el puente OpenAPI/REST. El servicio 8000 es el endpoint MCP HTTP nativo.

Instalación del Cliente

Usa los botones de un clic cuando tu cliente soporte deeplinks de instalación MCP, o copia la configuración JSON a continuación.

Configuración stdio recomendada:

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-host",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "mcp-token",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_PORT": "8006",
        "PROXMOX_VERIFY_SSL": "true"
      }
    }
  }
}

Usa un archivo de configuración local si prefieres no mantener credenciales en la configuración del cliente:

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_MCP_CONFIG": "/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"
      }
    }
  }
}

Ejemplos específicos por cliente para Claude Desktop, Cursor, VS Code, Codex, OpenCode, Open WebUI, Streamable HTTP y OpenAPI están en la Guía de Configuración del Cliente y la Guía de Integraciones.

Demo

Esta demo es una grabación directa de terminal de qwen/qwen3.6-plus manejando una sesión MCP en vivo en inglés contra un laboratorio local de Proxmox. Muestra el control en lenguaje natural fluyendo a través de herramientas MCP para crear e iniciar un LXC, ejecutar un comando en el contenedor y confirmar la superficie HTTP /health autenticada.

Recorded demo gif

Ver la versión MP4

Elige La Herramienta Correcta

Comienza con descubrimiento de solo lectura, luego pasa a herramientas de mutación solo después de que el nodo objetivo, almacenamiento, VMID y permisos estén claros.

Objetivo del operador	Comienza con	Luego usa	Notas
Inspeccionar el clúster	`get_nodes`, `get_cluster_status`	`get_storage`, `get_vms`, `get_containers`	Mejor primera verificación de salud después de la instalación del cliente
Crear o gestionar una VM	`get_nodes`, `get_storage`	`create_vm`, `start_vm`, `stop_vm`, `delete_vm`	Las mutaciones de larga duración devuelven `job_id` y `task_id` de Proxmox
Gestionar LXCs	`get_containers`, `get_storage`	`create_container`, `start_container`, `stop_container`, `delete_container`	Las herramientas de comandos respaldadas por SSH requieren la configuración opcional `ssh`
Revertir cambios riesgosos	`list_snapshots` con `vm_type=qemu` o `vm_type=lxc`	`create_snapshot`, `rollback_snapshot`, `delete_snapshot`	Crea un snapshot antes de pruebas destructivas de flujos de trabajo
Ejecutar comandos dentro de invitados	Herramientas de estado de VM o contenedor	`execute_vm_command`, `execute_container_command`	La ruta de VM necesita QEMU Guest Agent; la ruta de LXC necesita SSH al nodo Proxmox
Rastrear trabajo asíncrono	Respuesta de mutación con `job_id`	`poll_job`, `get_job`, `list_jobs`, `retry_job`, `cancel_job`	Usa `job_id` para conversaciones de agente/usuario y `task_id` para trazabilidad cruda de Proxmox
Inspeccionar registros	`get_node_syslog`, `get_cluster_log`	`get_task_log`, `get_node_firewall_log`, `get_guest_firewall_log`	Todas las herramientas de registro son de solo lectura; `get_task_log` acepta cualquier `UPID` de Proxmox
Automatizar desde herramientas HTTP	`/openapi.json`	`/jobs`, `/health`, rutas de herramientas generadas	Usa autenticación bearer y mantén CORS restringido fuera del desarrollo local

Para el mapa completo de herramientas, consulta la Guía de Selección de Herramientas y la Referencia de API y Herramientas.

Modelo de Seguridad

ProxmoxMCP-Plus es una capa de acceso, no un reemplazo para RBAC de Proxmox, controles de red o indicaciones de aprobación MCP del lado del cliente.

El proyecto brinda a los operadores varios puntos de control:

Los tokens de API de Proxmox deciden qué puede hacer el backend.
PROXMOX_API_KEY protege el puente OpenAPI por defecto.
MCP_API_KEY protege opcionalmente el endpoint nativo Streamable HTTP /mcp con autenticación Bearer.
La verificación TLS se aplica a menos que el modo de desarrollo esté explícitamente habilitado.
command_policy controla la ejecución de comandos y operaciones de alto riesgo.
approval_token puede controlar la ejecución de comandos y acciones mutantes de alto riesgo.
Las implementaciones MCP Streamable HTTP pueden usar protección contra rebinding de DNS además de listas de permitidos de Host y Origin.
Las listas de permitidos o denegados de herramientas MCP opcionales reducen la superficie de herramientas en runtime; no reemplazan el RBAC de Proxmox.
Los registros están diseñados para evitar exponer material de comandos y credenciales.

Lee la Guía de Seguridad antes de exponer el servidor fuera de un entorno local confiable.

Capacidades Principales de la Plataforma

ProxmoxMCP-Plus proporciona una superficie de control unificada para las tareas operativas que la mayoría de los equipos realmente necesitan en Proxmox VE. El mismo servidor puede exponer estos flujos de trabajo a clientes MCP para casos de uso de LLM y agentes de IA, y a consumidores HTTP a través del puente OpenAPI.

Áreas de flujo de trabajo soportadas:

Área de Capacidad	Disponibilidad
Crear / iniciar / detener / eliminar VM	Disponible
Crear / revertir / eliminar snapshot de VM	Disponible
Crear / restaurar copia de seguridad	Disponible
Descargar / eliminar ISO	Disponible
Crear / iniciar / detener / eliminar LXC	Disponible
Ejecución de comandos en contenedores respaldada por SSH	Disponible
Actualización de authorized_keys de contenedores	Disponible
Almacén persistente de trabajos para tareas largas	Disponible
Herramientas de control de trabajos MCP (`list_jobs`, `get_job`, `poll_job`, `cancel_job`, `retry_job`)	Disponible
Endpoints `/jobs` de OpenAPI con códigos de estado explícitos	Disponible
`/livez`, `/readyz`, `/health` y esquema OpenAPI local	Disponible
MCP Streamable HTTP nativo de Docker en `/mcp`	Disponible
Construcción de imagen Docker y `/livez`	Disponible

Puntos de entrada de validación y contrato en este repositorio:

pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75
ruff check .
mypy src --ignore-missing-imports
pip-audit -r requirements.txt
tests/integration/test_real_contract.py
tests/scripts/run_real_e2e.py

tests/scripts/run_real_e2e.py ahora prefiere proxmox-config/config.live.json o PROXMOX_MCP_E2E_CONFIG. Esto evita ejecutar accidentalmente verificaciones en vivo contra un config.json predeterminado específico de la máquina.

Trabajos de Larga Duración

Muchas mutaciones de Proxmox son asíncronas. ProxmoxMCP-Plus ahora envuelve esas tareas en una capa de trabajos persistente para que los clientes MCP y OpenAPI puedan rastrearlas a través de un Job ID estable.

Las herramientas de larga duración como crear/iniciar/detener VM, crear/iniciar/detener contenedor, cambios de snapshot, copia de seguridad/restauración y descarga/eliminación de ISO ahora devuelven ambos:

task_id: el UPID crudo de Proxmox
job_id: el registro de trabajo persistente del lado del servidor

El registro de trabajo almacena:

estado actual y progreso
conteo de reintentos y UPIDs anteriores
último payload de resultado o razón de fallo
historial de auditoría para acciones de crear, sondear, reintentar y cancelar

Por defecto, el almacén de trabajos persiste en proxmox-jobs.sqlite3, por lo que un reinicio no pierde metadatos de trabajos en curso o completados.

Herramientas de Trabajo MCP

list_jobs
get_job
poll_job
cancel_job
retry_job

Rutas de Trabajo OpenAPI

Cuando el proxy OpenAPI está habilitado y hay un JobStore local disponible, estas rutas se exponen directamente:

Ruta	Método	Propósito	Códigos de éxito
`/jobs`	`GET`	listar trabajos persistidos	`200`
`/jobs/{job_id}`	`GET`	obtener un trabajo, opcional `refresh=true`	`200`
`/jobs/{job_id}/poll`	`POST`	actualizar estado desde Proxmox	`200`
`/jobs/{job_id}/cancel`	`POST`	solicitar cancelación	`202`
`/jobs/{job_id}/retry`	`POST`	reproducir una receta de reintento almacenada	`202`

Códigos de error comunes:

404: job_id desconocido
409: el trabajo existe pero esa operación no es válida ahora
503: el proxy OpenAPI se inició sin un JobStore local

tests/scripts/run_real_e2e.py ahora prefiere proxmox-config/config.live.json o PROXMOX_MCP_E2E_CONFIG. Esto evita ejecutar accidentalmente comprobaciones en vivo contra un config.json predeterminado específico de la máquina.

Posicionamiento frente a enfoques comunes

Capacidad	API oficial de Proxmox	Scripts puntuales	ProxmoxMCP-Plus
MCP para flujos de trabajo de LLM y agentes de IA	No	No	Sí
Superficie OpenAPI para herramientas HTTP estándar	No	Generalmente no	Sí
Operaciones de VM y LXC en una sola interfaz	Solo bajo nivel	Depende	Sí
Flujos de trabajo de instantáneas, copias de seguridad y restauración	Solo bajo nivel	Depende	Sí
Seguimiento persistente de trabajos asíncronos y reintentos	No	Raro	Sí
Ejecución de comandos en contenedores con controles de política	No	Solo personalizado	Sí
Ruta de distribución Docker	No	Raro	Sí
Verificación de entorno en vivo a nivel de repositorio	N/D	Raro	Sí

Plantillas de escenarios

Ejemplos listos para copiar están en docs/examples/:

Están escritos tanto para operadores humanos como para uso impulsado por LLM.

Documentación

El README está optimizado intencionalmente para una comprensión rápida en GitHub. La documentación operativa más extensa vive en docs/wiki/ y también se puede publicar en la Wiki de GitHub.

Si necesitas...	Comienza aquí
Entender el proyecto y el flujo de despliegue	Inicio de la Wiki
Configurar y ejecutar contra un entorno Proxmox	Guía del operador
Conectar Claude Desktop, Cursor, VS Code, Codex, Open WebUI o clientes HTTP	Guía de configuración de clientes
Elegir la herramienta adecuada para un flujo de trabajo	Guía de selección de herramientas
Revisar objetivos de calidad de documentación, plan de medios y lista de verificación de publicación	Plan de calidad de documentación
Revisar patrones de integración y detalles de transporte	Guía de integraciones
Instalar desde IDE y agentes compatibles con MCP	Instalación de agentes
Habilitar ejecución de comandos LXC a través de SSH	Ejecución de comandos en contenedores
Revisar seguridad y política de comandos	Guía de seguridad
Inspeccionar parámetros de herramientas, requisitos previos y comportamiento	Referencia de API y herramientas
Depurar problemas de inicio, autenticación o salud	Solución de problemas
Trabajar en el código base o publicarlo	Guía para desarrolladores
Revisar notas de versión y actualización	Notas de versión y actualización

Wiki publicada:

Inicio de la Wiki de GitHub

Estructura del repositorio

src/proxmox_mcp/: servidor MCP, carga de configuración, seguridad, puente OpenAPI
main.py: punto de entrada MCP para uso local y controlado por cliente
docker-compose.yml: tiempo de ejecución HTTP/OpenAPI
requirements/: fuentes de dependencias auxiliares y listas de instalación en tiempo de ejecución
scripts/: scripts de inicio auxiliares para flujos de trabajo locales
tests/scripts/run_real_e2e.py: ruta en vivo de Proxmox y Docker/OpenAPI
tests/: cobertura de pruebas unitarias y de integración
docs/examples/: indicaciones basadas en escenarios y ejemplos HTTP
docs/wiki/: documentación extensa para operadores, integraciones y referencias

Comprobaciones de desarrollo

pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75
ruff check .
mypy src --ignore-missing-imports
pip-audit -r requirements.txt
python -m build

Se requiere Paramiko 5.0.0 o más reciente para que pip-audit pueda ejecutarse sin una excepción de CVE-2026-44405.

Licencia

MIT