NANDI Proxmox MCP

Convierte tu clúster de Proxmox en una plataforma impulsada por IA con más de 140 herramientas para automatización, monitorización y ejecución controlada.

Servidor MCP de código abierto para Proxmox VE, impulsado por NANDI Services.

nandi-proxmox-mcp expone el inventario, ciclo de vida, almacenamiento, copias de seguridad, redes, cortafuegos, acceso, monitorización, diagnósticos SSH y operaciones remotas/de contenedor protegidas de Proxmox sin eliminar las medidas de seguridad necesarias para clústeres de producción.

Qué permanece habilitado

Más de 140 herramientas para nodos, clúster, QEMU, LXC, almacenamiento, copias de seguridad, tareas, red, cortafuegos, pools, acceso, plantillas, monitorización y operaciones remotas.
Niveles de acceso: read-only, read-execute, full.
División de módulos: PVE_MODULE_MODE=core|advanced.
Filtros de herramientas: PVE_CATEGORIES, PVE_TOOL_BLACKLIST, PVE_TOOL_WHITELIST.
Medidas de seguridad para operaciones destructivas mediante confirm=true.
Alias compatibles con versiones anteriores como listNodes, getVMStatus, startVM, stopContainer.
Transporte stdio para clientes MCP y transporte HTTP transmitible para despliegues remotos controlados.

Permisos requeridos

El servidor necesita dos canales de confianza y ambos se conservan intencionadamente:

Token de API de Proxmox
- Utilizado para inventario, ciclo de vida, configuración y puntos finales de gestión.
- Mantén las ACL al mínimo: concede solo los roles necesarios para las herramientas que realmente habilites.
Acceso SSH por lotes al host de Proxmox
- Requerido para pct exec, diagnósticos SSH por lotes y herramientas de inspección de Docker a nivel de contenedor.
- Esto sigue siendo necesario porque la cobertura de la API de Proxmox no reemplaza a pct en el lado del host ni a los diagnósticos basados en SSH.

Más detalles: docs/PERMISSIONS.md

Confirmaciones para operaciones destructivas

Las operaciones marcadas como destructivas no se ejecutan a menos que el llamador envíe confirm=true.

Ejemplos:

Detener, apagar, reiniciar, suspender, eliminar, migrar, revertir instantánea de VM/contenedor
Escrituras en almacenamiento/red/cortafuegos/acceso que pueden alterar el estado del clúster
Ejecución remota avanzada como pve_exec_in_container

El servidor devuelve un error estructurado CONFIRMATION_REQUIRED cuando falta la confirmación. Este comportamiento no ha cambiado y se ha reforzado.

Niveles de acceso

read-only
- Inventario, estado, registros, métricas y diagnósticos que no modifican el sistema.
read-execute
- Solo lectura más acciones seleccionadas de ejecución/ciclo de vida.
full
- Operaciones de creación, actualización, eliminación, migración, restauración y nivel de administrador.

PVE_MODULE_MODE=core oculta las herramientas avanzadas sin renombrar ni eliminar los IDs de herramientas canónicos de la base de código.

Configuración en tiempo de ejecución

Variables de entorno

Requeridas:

PROXMOX_HOST
PROXMOX_USER
PROXMOX_REALM
PROXMOX_TOKEN_NAME
PROXMOX_TOKEN_SECRET
PROXMOX_SSH_HOST
PROXMOX_SSH_USER
PROXMOX_SSH_KEY_PATH

Opcionales:

PROXMOX_PORT por defecto 8006
PROXMOX_SSH_PORT por defecto 22
PROXMOX_ALLOW_INSECURE_TLS por defecto false
PVE_ACCESS_TIER=read-only|read-execute|full
PVE_MODULE_MODE=core|advanced
PVE_CATEGORIES
PVE_TOOL_BLACKLIST
PVE_TOOL_WHITELIST

Transporte HTTP:

MCP_TRANSPORT=stdio|http
MCP_HOST por defecto 0.0.0.0
MCP_PORT por defecto 3000
MCP_ALLOWED_HOSTS
MCP_ALLOWED_ORIGINS
MCP_RATE_LIMIT_WINDOW_MS
MCP_RATE_LIMIT_MAX
MCP_MAX_BODY_SIZE_BYTES
MCP_HEADERS_TIMEOUT_MS
MCP_REQUEST_TIMEOUT_MS
MCP_KEEPALIVE_TIMEOUT_MS
MCP_MAX_HEADERS_COUNT

Archivo de configuración local

La configuración escribe .nandi-proxmox-mcp/config.json y .vscode/mcp.json.

El cargador de configuración ahora rechaza:

rutas de configuración vacías o mal formadas
archivos de configuración demasiado grandes
caracteres de control en las rutas de configuración

Inicio rápido

Configuración guiada:

npx nandi-proxmox-mcp setup
npx nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op

Ejecución directa con variables de entorno:

$env:PROXMOX_HOST="pve.local"
$env:PROXMOX_PORT="8006"
$env:PROXMOX_USER="svc_mcp"
$env:PROXMOX_REALM="pve"
$env:PROXMOX_TOKEN_NAME="nandi-mcp"
$env:PROXMOX_TOKEN_SECRET="<SECRET>"
$env:PROXMOX_SSH_HOST="pve.local"
$env:PROXMOX_SSH_USER="root"
$env:PROXMOX_SSH_KEY_PATH="$env:USERPROFILE\.ssh\id_ed25519"

npx nandi-proxmox-mcp run

Modelo de seguridad y riesgo residual

Este servidor MCP opera sobre infraestructura real de Proxmox y no es un entorno aislado (sandboxed).

Suposiciones de confianza

El servidor se despliega en un entorno de confianza
Solo operadores autorizados pueden acceder a él
La exposición a la red está controlada (no expuesto públicamente)
Las credenciales se gestionan de forma segura

Riesgos residuales

Los siguientes riesgos son inherentes al diseño del sistema:

Operaciones privilegiadas
El nivel de acceso completo y las capacidades de ejecución en contenedores pueden realizar acciones destructivas o a nivel de sistema.
Límite de ejecución SSH
La ejecución de comandos remotos depende de SSH y hereda la postura de seguridad del sistema de destino.
Modo TLS inseguro opcional
Cuando está habilitado (PROXMOX_ALLOW_INSECURE_TLS=true), se omite la validación del certificado TLS y puede exponer las conexiones a ataques MITM. Destinado solo para uso en laboratorio.
Sincronización de dependencias externas
La distribución de paquetes y la visibilidad de los listados dependen de npm, el registro MCP y los tiempos de propagación del mercado.

Responsabilidades de seguridad

Los usuarios son responsables de:

Restringir el acceso solo a operadores de confianza
Utilizar tokens de API y claves SSH con privilegios mínimos
Evitar TLS inseguro en entornos de producción
Asegurar adecuadamente la infraestructura subyacente

Controles de seguridad implementados

Niveles de acceso (read-only, read-execute, full)
Confirmación requerida para operaciones destructivas
Validación de entrada y endurecimiento de comandos
Limitación de tasa (rate limiting) y validación de solicitudes

Endurecimiento HTTP

Cuando MCP_TRANSPORT=http está habilitado, el servidor ahora aplica:

cumplimiento de lista blanca de hosts, incluida la protección contra enlaces comodín
validación de origen para solicitudes que envían un encabezado Origin
límites explícitos de tamaño de cuerpo y respuestas 413 saneadas
limitación de tasa en /mcp
tiempos de espera de solicitud/encabezado/keep-alive
X-Content-Type-Options: nosniff
Cache-Control: no-store
cargas útiles de error saneadas sin seguimientos de pila (stack traces)

Puntos finales de salud/preparación:

GET /health
GET /ready
POST /mcp

Endurecimiento de SSH y ejecución de comandos

La funcionalidad no ha cambiado, pero la ruta de ejecución es más estricta:

la ejecución de comandos locales sigue usando spawn(..., { shell: false })
los valores de host/usuario SSH no pueden ocultar opciones de CLI
SSH utiliza BatchMode, IdentitiesOnly, autenticación de clave pública y controles explícitos de vivacidad de conexión
los búferes de salida están limitados para evitar un crecimiento de memoria ilimitado
dockerLogsInContainer ahora valida y escapa los nombres de los contenedores en lugar de interpolar la entrada bruta del usuario
la ejecución arbitraria de comandos en contenedores sigue estando disponible solo a través del flujo pve_exec_in_container, que ya es destructivo y requiere confirmación

Postura de seguridad

Mitigaciones en el repositorio:

versiones de dependencias directas fijadas y overrides de npm para paquetes transitivos críticos
metadatos de paquetes verificables y enlaces de repositorio para escáneres de npm/paquetes
validación de sincronización de descriptor/versión para artefactos de npm, registro y mercado
redacción de valores similares a tokens/encabezados/contraseñas en los registros
no se devuelven seguimientos de pila ni secretos a los clientes
puertas de CI para lint, comprobación de tipos, compilación, pruebas, validación de metadatos, sincronización de descriptores, npm pack --dry-run y auditoría

Modelo de amenazas y riesgos residuales: docs/THREAT_MODEL.md

Flujo de publicación

El orden de lanzamiento es estricto:

npm run lint
npm run typecheck
npm run build
npm test
npm audit --include=dev --audit-level=moderate
npm ls express
npm ls path-to-regexp
npm pack --dry-run
npm pack
npm whoami
npm publish --access public
npm view nandi-proxmox-mcp version
mcp-publisher validate .mcp/server.json
mcp-publisher publish .mcp/server.json

El release.yml basado en etiquetas ahora publica primero en npm y solo después publica el descriptor del Registro MCP, evitando la deriva entre npm y el registro en la misma versión.

Reserva manual y solución de problemas: docs/RELEASE.md

Desarrollo

npm ci
npm run lint
npm run typecheck
npm run build
npm test
npm run validate:release
npm pack --dry-run

Política de mantenimiento de la documentación

Este repositorio aplica una puerta de sincronización de documentación previa al commit.

Antes de cerrar un change, fix o refactor, evalúa si README.md, AGENTS.md y CONTRIBUTING.md deben actualizarse.
Si un documento es relevante para el impacto conductual o de proceso, debe actualizarse en el mismo conjunto de cambios.
Si no se necesita ninguna actualización, se requiere una justificación explícita no-doc-change.
Una tarea no se considera lista para el commit hasta que se satisfaga esta puerta.

Documentación

Registro y mercado

npm: https://www.npmjs.com/package/nandi-proxmox-mcp
Registro MCP: https://registry.modelcontextprotocol.io/
Listado en el mercado MCP: https://mcp-marketplace.io/server/io-github-nandi-services-nandi-proxmox-mcp

Licencia

MIT. Ver LICENSE.

nandi-proxmox-mcp