Proxmox MCP Suite

Proxmox MCP Suite

Gestiona tu clúster Proxmox VE y tu Backup Server desde Claude — de forma profunda, segura y sin saturar la ventana de contexto.

Inicio rápido · Por qué esta suite · Qué incluye · Seguridad · Configuración

---

Dos servidores Model Context Protocol, empaquetados como plugins de Claude Code, que convierten a Claude en un operador Proxmox competente — 69 herramientas entre virtualización y backup, diseñadas para ejecutarse dentro del contexto de un LLM: salida compacta, salud en una sola llamada, resultados de tareas en línea y un modelo de seguridad de dos niveles con vistas previas de dry-run y un registro de auditoría a prueba de manipulaciones.

⚡ Inicio rápido

Requisito: Claude Code y uv (uvx). Los servidores se ejecutan mediante uvx — no hay que pip install manualmente.

/plugin marketplace add ahmetem/proxmox-mcp-suite
/plugin install proxmox-ve@proxmox-mcp-suite
/plugin install proxmox-backup@proxmox-mcp-suite

Exporta tus credenciales de Proxmox (consulta Configuración), reinicia Claude Code y pregunta:

"¿Cómo está el servidor? ¿Algún almacenamiento llenándose?" — una llamada a proxmox_health_overview.

"Haz un snapshot de la VM 102 como pre-actualización y luego reiníciala."

"¿Está sano mi último backup del CT 200?"

🎯 Por qué esta suite

La mayoría de los servidores MCP de Proxmox envuelven la API y le entregan a Claude JSON crudo. Esta está construida para lo que realmente limita a un agente — el contexto — y para no romper tu infraestructura.

	Proxmox MCP Suite	MCP Proxmox típico
Salida	JSON compacto y con límite de longitud · health_overview en una llamada · filtros de lista · proyección fields	Volcados completos y verbosos
Lanzamiento de tareas	wait_seconds consulta la tarea y devuelve el resultado final en línea	Dispara y luego una segunda llamada para ver el estado
Mutaciones	Puerta de dos niveles: confirm + i_understand_data_loss, además de vistas previas dry_run en las más riesgosas	Un solo flag, o nada
Auditabilidad	Ejecución de shell en host/guest añadida a un registro encadenado por hash y a prueba de manipulaciones (proxmox_audit_verify)	Registro simple, o ninguno
Profundidad (VE)	Invitados, snapshots, backups, almacenamiento, discos, LVM, ZFS completo, preparación de discos, aprovisionamiento, forense de tareas, auto-reparación de backups	Solo ciclo de vida de VM/CT
Backup (PBS)	Servidor dedicado: datastores, snapshots, GC, verificación, prune, solo lectura por defecto	Generalmente ausente
Instalación	Un marketplace, uvx — cero configuración manual de Python	Clonar + venv + pip + configuración JSON

Diseño modular: instala solo Proxmox VE, solo PBS, o ambos.

📦 Qué incluye

proxmox-ve — 52 herramientas

_{Repositorio: homelab-proxmox-mcp}

• Invitados — listar/estado, crear VM y LXC desde cero, clonar, encender, redimensionar
• Snapshots — crear / revertir / eliminar (con protección ante pérdida de datos)
• Backups — crear / listar / restaurar vzdump (rechaza sobrescritura silenciosa)
• Almacenamiento y discos — pools, desglose de uso, discos físicos + SMART
• LVM / ZFS — VG/thin, ZFS completo: pools, datasets, snapshots, scrub, send, propiedades, preparación de discos y aprovisionamiento
• Ejecución — SSH en VM invitada, SSH en host (gratuito + una variante de solo lectura con lista blanca segura para agentes), pct exec de LXC, control de servicios, cola de logs
• Forense y auto-reparación — lista/logs de tareas, inspección de trabajos de backup, limpieza de snapshots @vzdump obsoletos que desbloquea backups fallidos

proxmox-backup — 17 herramientas

_{Repositorio: homelab-pbs-mcp}

• Datastores y snapshots — estado, uso, listar, proteger/olvidar
• Mantenimiento — recolección de basura, trabajos de verificación, prune (con dry-run)
• Tareas — estado y logs por UPID
• Solo lectura por defecto — las herramientas de escritura permanecen inactivas hasta PBS_ALLOW_WRITE=true

🛡️ Modelo de seguridad

Las herramientas de solo lectura se ejecutan libremente. Todo lo que cambia el estado requiere confirm=true; cualquier cosa que destruya datos persistentes además requiere i_understand_data_loss=true — así que Claude solo las dispara después de que lo pidas explícitamente.

• Vistas previas dry_run en las mutaciones de mayor consecuencia (crear VM/CT, clonar, restaurar) devuelven la llamada API exacta que harían (con secretos enmascarados), sin tocar nada.
• Auditoría a prueba de manipulaciones — cada ejecución de shell en host/guest se añade a un registro encadenado por hash (SHA-256, o HMAC-SHA256 con PROXMOX_AUDIT_HMAC_KEY). proxmox_audit_verify recalcula la cadena y marca cualquier línea alterada, eliminada o reordenada.
• Autenticación por token, nunca contraseñas de root — los tokens de API son revocables y limitan el radio de impacto.

⚙️ Configuración

Las credenciales se pasan a los servidores mediante variables de entorno — expórtalas en el shell que lanza Claude Code (ningún secreto se guarda en el plugin).

Proxmox VE — obligatorias: PROXMOX_HOST, PROXMOX_USER, PROXMOX_TOKEN_NAME, PROXMOX_TOKEN_VALUE. Opcionales: PROXMOX_PORT, PROXMOX_VERIFY_SSL, y el PROXMOX_SSH_* de las herramientas basadas en SSH. → lista completa en el repositorio del servidor.

Proxmox Backup Server — obligatorias: PBS_HOST, PBS_TOKEN_ID, PBS_TOKEN_SECRET, PBS_NODE. Opcionales: PBS_VERIFY_TLS, PBS_DEFAULT_DATASTORE, y PBS_ALLOW_WRITE (controla GC/prune/forget). → repositorio del servidor PBS.

Verifica que los servidores se cargaron con /mcp.

🔧 Cómo se ejecuta

Cada plugin lanza su servidor con uvx, que lo obtiene, instala y aísla automáticamente desde PyPI (pve-mcp, pbs-mcp) — sin clonar, sin virtualenv, sin pip install manual. uvx guarda en caché el entorno después del primer lanzamiento, así que los inicios posteriores son instantáneos. Para fijar una versión específica, establece el args de un plugin a por ejemplo ["pve-mcp==1.2.0"].

🔒 Notas de seguridad

• Mantén las APIs de Proxmox / PBS en una LAN de confianza o detrás de una VPN.
• Separa los privilegios de los tokens de API; otorga el rol más restringido que funcione.
• No elimines las protecciones confirm / i_understand_data_loss.

📄 Licencia

GNU General Public License v3.0. No afiliado ni respaldado por Proxmox Server Solutions GmbH. "Proxmox" es una marca registrada de su respectivo propietario.