proxmox-ai

Servidor MCP que permite a un agente de IA administrar Proxmox VE en lenguaje natural, sin darle nunca más poder del estrictamente necesario.

"¿Qué contenedores están ejecutándose?"        → responde
"¿Cuál está consumiendo más RAM?"              → responde
"Reinicia el CT 105"                           → propone, espera confirmación, ejecuta
"Haz rollback del snapshot pre-update"         → exige una frase literal del humano
"Borra el CT 105"                              → no existe esa herramienta

El diseño parte de una idea: el modelo propone, el motor de políticas decide y el registro de auditoría lo recuerda.

---

Estado

Fase 1 (solo lectura) implementada y probada. Las fases 2 a 5 están implementadas pero desactivadas por defecto: se habilitan una a una con variables de entorno, y cada una necesita además su privilegio en la ACL de Proxmox. Ver docs/roadmap.md.

Herramientas MCP	27
Tests	229 (pytest)
Dependencias	mcp, httpx
Python	≥ 3.11

---

Instalación rápida

En el nodo Proxmox, crea el usuario y el token dedicados:

./scripts/setup-proxmox-user.sh

Copia el secreto del token: Proxmox no lo vuelve a mostrar.

En el contenedor donde vivirá el MCP (ver docs/instalacion.md para crearlo):

git clone https://github.com/dallaswk/proxmox-ai.git
cd proxmox-ai
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env && chmod 600 .env
$EDITOR .env          # PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET

Comprueba que arranca y que ve la infraestructura:

set -a && . ./.env && set +a
proxmox-ai            # habla MCP por stdin/stdout; Ctrl-C para salir

Conéctalo a tu cliente MCP (Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "proxmox": {
      "command": "/opt/proxmox-ai/.venv/bin/proxmox-ai",
      "env": {
        "PROXMOX_HOST": "proxmox.midominio.local",
        "PROXMOX_TOKEN_ID": "ai-agent@pve!mcp",
        "PROXMOX_TOKEN_SECRET": "...",
        "PROXMOX_AI_READ_ONLY": "true",
        "PROXMOX_AI_AUDIT_LOG": "/var/log/proxmox-ai/audit.jsonl"
      }
    }
  }
}

---

Cómo funciona la seguridad

Cuatro capas independientes. Cada una vale por sí sola:

1. La ACL de Proxmox. Es la frontera real. El token es un usuario dedicado con --privsep 1, nunca root@pam, y en la Fase 1 sólo tiene PVEAuditor. Un token que no puede borrar una VM no la borra ni aunque todo lo demás falle.

2. Flags de capacidad. PROXMOX_AI_READ_ONLY=true bloquea cualquier escritura sin importar el resto de la configuración. Cada fase tiene su propio flag, y las operaciones irreversibles necesitan uno adicional.

3. Confirmación en dos pasos. Una herramienta de escritura llamada sin confirm_token no toca nada: devuelve un plan y un token de un solo uso ligado a esa acción exacta. El humano ve el plan entre las dos llamadas. Para las operaciones irreversibles hay que enviar además una frase literal (CONFIRMO ROLLBACK SNAPSHOT 105); un "sí" no basta.

4. Sin shell arbitrario. No hay execute_any_command. Los comandos dentro de los guests pasan por una lista blanca de argv, con dos listas negras por delante —binarios (rm, dd, bash…) y opciones destructivas— y rechazo de metacaracteres de shell. La lista negra de opciones existe porque un binario que parece de lectura puede tener un flag que no lo es: journalctl -u nginx --vacuum-time=1s borra los logs archivados. Los argumentos se escapan además con shlex.quote, porque ssh host cmd siempre lo reinterpreta el shell remoto.

Y por debajo de todo, un registro JSONL append-only con cada intento —incluidos los rechazados— y sin un solo secreto.

Lo que esto no resuelve: un servidor MCP no puede distinguir "el humano dijo sí" de "el modelo decidió seguir". La confirmación en dos pasos garantiza que nada irreversible ocurre como efecto colateral de una sola llamada, y deja rastro de todo, pero la garantía dura es la ACL. Está explicado sin adornos en docs/modelo-de-seguridad.md.

---

Herramientas

Fase 1 — lectura (activa por defecto, sólo necesita PVEAuditor)

Herramienta	Para qué
pve_policy_status	Qué está permitido ahora mismo
pve_list_nodes	Nodos con CPU, RAM y disco raíz
pve_list_guests	LXC y VMs con su consumo; de aquí salen los VMID
pve_top_consumers	Ranking por RAM, CPU o disco
pve_guest_status	Estado detallado de un guest
pve_guest_config	Configuración: cores, memoria, discos, red
pve_guest_metrics	Históricos RRD: distingue pico de problema sostenido
pve_storage_status	Espacio libre, con alertas al 85% y 92%
pve_recent_tasks	Tareas recientes y cuáles fallaron
pve_task_log	Log completo de una tarea
pve_list_snapshots	Snapshots de un guest
pve_list_backups	Backups disponibles
pve_health_report	Revisión completa: nodos, guests, storage, tareas

Fase 2 — encendido (PROXMOX_AI_ENABLE_POWER, priv. VM.PowerMgmt)

pve_guest_power — start, shutdown, reboot, stop. Confirmación obligatoria.

Fase 3 — snapshots (PROXMOX_AI_ENABLE_SNAPSHOT, priv. VM.Snapshot)

pve_create_snapshot (nivel 1) · pve_rollback_snapshot y pve_delete_snapshot (nivel 2: frase literal + PROXMOX_AI_ENABLE_DESTRUCTIVE)

Fase 4 — backups (PROXMOX_AI_ENABLE_BACKUP, priv. VM.Backup)

pve_create_backup — nivel 1. La restauración no está implementada a propósito: es la operación más destructiva de Proxmox. Ver docs/modelo-de-seguridad.md.

Fase 5 — diagnóstico dentro de los guests (PROXMOX_AI_ENABLE_GUEST_EXEC)

Herramienta	Para qué
guest_list_allowed_commands	Qué puede ejecutar el agente
guest_check_service	¿Está nginx arriba?
guest_read_logs	journalctl, opcionalmente sólo errores
guest_resources	df/free/uptime vistos desde dentro
guest_docker_ps · guest_docker_logs	Estado y logs de contenedores Docker
guest_run_command	Un comando de la lista blanca
guest_diagnose_web	Diagnóstico completo del stack web
guest_restart_service	Reinicia un servicio. Nivel 1

---

Ejemplo real de la confirmación en dos pasos

Usuario:  Reinicia el CT 105.

Agente:   [pve_guest_power vmid=105 operation=reboot]
          → confirmation_required
            "REBOOT CT 105 (web-production) on node pve1 — will request a
             clean reboot via the guest OS."
            nothing_has_changed: true
            confirm_token: "kJ8x...b2"

          Voy a reiniciar el CT 105 (web-production) en el nodo pve1.
          Es un reinicio limpio a través del sistema operativo. ¿Confirmas?

Usuario:  Sí.

Agente:   [pve_guest_power vmid=105 operation=reboot confirm_token="kJ8x...b2"]
          → status: completed

          Reiniciado. La tarea terminó con estado OK.

Si el agente intentara usar ese mismo token para el CT 101, o para un stop en lugar de un reboot, el motor lo rechazaría: el token está ligado por HMAC a la acción exacta, el guest y los parámetros.

---

Desarrollo

pip install -e ".[dev]"
pytest                    # 229 tests, sin red ni Proxmox real
ruff check src tests

Los tests usan httpx.MockTransport con un clúster falso (1 nodo, 2 CT, 1 VM, 2 storages). No hace falta un Proxmox para desarrollar.

Documentación

• docs/instalacion.md — instalación paso a paso
• docs/modelo-de-seguridad.md — amenazas y límites
• docs/roadmap.md — las 7 fases, con checklist
• docs/especificacion-original.md — el documento de partida

Licencia

MIT