proxmox-ai
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 herramientaEl 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 ( |
Dependencias |
|
Python | ≥ 3.11 |
Related MCP server: mcp-server-proxmox
Instalación rápida
En el nodo Proxmox, crea el usuario y el token dedicados:
./scripts/setup-proxmox-user.shCopia 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_SECRETComprueba que arranca y que ve la infraestructura:
set -a && . ./.env && set +a
proxmox-ai # habla MCP por stdin/stdout; Ctrl-C para salirConé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é |
| Qué está permitido ahora mismo |
| Nodos con CPU, RAM y disco raíz |
| LXC y VMs con su consumo; de aquí salen los VMID |
| Ranking por RAM, CPU o disco |
| Estado detallado de un guest |
| Configuración: cores, memoria, discos, red |
| Históricos RRD: distingue pico de problema sostenido |
| Espacio libre, con alertas al 85% y 92% |
| Tareas recientes y cuáles fallaron |
| Log completo de una tarea |
| Snapshots de un guest |
| Backups disponibles |
| 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é |
| Qué puede ejecutar el agente |
| ¿Está nginx arriba? |
| journalctl, opcionalmente sólo errores |
|
|
| Estado y logs de contenedores Docker |
| Un comando de la lista blanca |
| Diagnóstico completo del stack web |
| 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 testsLos 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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Related MCP Servers
- FlicenseBqualityDmaintenanceA Python MCP server for Proxmox VE that lets AI agents read cluster status, power guests on/off, and provision new VMs/containers through natural language, while preventing any destructive actions.29-
- AlicenseBqualityCmaintenanceA Model Context Protocol (MCP) server for Proxmox Virtual Environment that enables AI assistants to manage virtual machines, containers, nodes, and resources through natural language interactions.104MIT
- AlicenseAqualityBmaintenanceAI-powered MCP server for managing Proxmox VE VMs and containers with built-in governance, audit logging, and reversibility.435MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for Proxmox VE that enables AI assistants to inspect and manage LXC containers, VMs, snapshots, and resource pools via the Proxmox API.-