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.

Related MCP server: ProxmoxMCP

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:

1. npm run lint

2. npm run typecheck

3. npm run build

4. npm test

5. npm audit --include=dev --audit-level=moderate

6. npm ls express

7. npm ls path-to-regexp

8. npm pack --dry-run

9. npm pack

10. npm whoami

11. npm publish --access public

12. npm view nandi-proxmox-mcp version

13. mcp-publisher validate .mcp/server.json

14. 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

• docs/QUICKSTART.md

• docs/PERMISSIONS.md

• docs/SECURITY.md

• docs/THREAT_MODEL.md

• docs/RELEASE.md

• docs/TROUBLESHOOTING.md

• docs/TOOLS.md

• docs/MARKETPLACE_GO_LIVE.md

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.