Proxmox-mcp

Name: proxmox-mcp
Author: akmalovaa

Release License: MIT Python 3.14 GHCR MCP

Proxmox MCP sencillo

Servidor MCP para gestionar Proxmox VE

38 herramientas: nodos, máquinas virtuales QEMU, contenedores LXC, almacenamiento, clúster e instantáneas.

¿Por qué esta opción?

Una sola imagen, multiarquitectura: docker run ghcr.io/akmalovaa/proxmox-mcp:latest y listo.
Solo variables de entorno: sin archivos de configuración, sin base de datos, sin estado.
Solo lectura por defecto: las operaciones destructivas están protegidas por un PROXMOX_RISK_LEVEL explícito.
Código base diminuto: MCP puro vía stdio sobre Proxmoxer, sin servidor HTTP, sin capa de autenticación, sin extras.
Salida JSON sin procesar: sin formato, sin emojis; el LLM recibe datos limpios.

Inicio rápido

Imagen: ghcr.io/akmalovaa/proxmox-mcp:latest (multiarquitectura: amd64 + arm64).

1. Exporta las credenciales en tu perfil de shell (~/.zprofile, ~/.zshrc o ~/.bashrc):

# base environment:
export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_PASSWORD=your-password

# or use token auth (recommended):
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# optional:
export PROXMOX_RISK_LEVEL=read

Recarga: source ~/.zprofile (o reinicia la shell).

2. Añádelo a ~/.claude/settings.json (Claude Code) o claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_PASSWORD",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

o autenticación por token:

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_TOKEN_NAME",
        "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

docker run -e VAR sin valor pasa la variable del host directamente; sin secretos en el archivo de configuración. Reinicia el cliente: 38 herramientas de Proxmox estarán disponibles.

Para autenticación por contraseña, cambia las variables de token por PROXMOX_PASSWORD.

Nota: Claude Desktop en macOS se inicia a través de launchd y no hereda ~/.zprofile/~/.zshrc. Coloca las exportaciones en ~/.zshenv o recurre a un bloque "env": { ... } en línea dentro de la configuración.

Configuración

Todos los ajustes son variables de entorno: establécelas en tu perfil de shell, pásalas en línea a docker run -e o decláralas en el bloque env de tu cliente MCP.

Variable	Por defecto	Descripción
`PROXMOX_HOST`	—	Host de Proxmox (IP o nombre de host)
`PROXMOX_USER`	`root@pam`	Usuario de API
Auth	—
`PROXMOX_PORT`	`8006`	Puerto de API
`PROXMOX_VERIFY_SSL`	`false`	Verificar certificado TLS
`PROXMOX_RISK_LEVEL`	`read`	`read` / `lifecycle` / `all`

Autenticación: token o contraseña

Elige una. Si ambas están configuradas, el token tiene prioridad.

Token (recomendado): créalo en la interfaz de Proxmox: Datacenter → Permissions → API Tokens → Add (desmarca Privilege Separation). Luego:

export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Contraseña (alternativa):

export PROXMOX_PASSWORD=your-password

Niveles de riesgo

PROXMOX_RISK_LEVEL controla las operaciones destructivas:

Nivel	Añade
`read` (por defecto)	herramientas de solo lectura
`lifecycle`	+ start / stop / reboot / suspend / clone / create-snapshot
`all`	+ delete-snapshot / rollback-snapshot

Cada llamada elevada se registra en stderr (ALLOW / DENY + herramienta + nivel).

Herramientas

Nodos (7)

Herramienta	Descripción
`list_nodes`	Lista todos los nodos del clúster con estado, CPU, memoria y tiempo de actividad
`get_node_status`	Métricas detalladas del nodo (CPU, memoria, disco, carga, kernel)
`get_node_networks`	Interfaces de red en un nodo
`get_node_disks`	Discos físicos en un nodo
`get_node_tasks`	Tareas recientes en un nodo
`get_task_status`	Estado de una tarea específica por UPID
`get_task_log`	Salida de registro de una tarea

Máquinas virtuales QEMU (14)

Herramienta	Nivel	Descripción
`list_vms`	read	Lista todas las VM, opcionalmente filtradas por nodo
`get_vm_status`	read	Estado actual de la VM (en ejecución/detenida, CPU, memoria)
`get_vm_config`	read	Configuración de la VM (hardware, discos, red)
`list_vm_snapshots`	read	Lista todas las instantáneas de una VM
`start_vm`	lifecycle	Iniciar una VM
`stop_vm`	lifecycle	Detener forzosamente una VM
`shutdown_vm`	lifecycle	Apagado ACPI elegante con tiempo de espera
`reboot_vm`	lifecycle	Reiniciar vía ACPI
`suspend_vm`	lifecycle	Suspender una VM
`resume_vm`	lifecycle	Reanudar una VM suspendida
`clone_vm`	lifecycle	Clonación completa o vinculada
`create_vm_snapshot`	lifecycle	Crear una instantánea
`delete_vm_snapshot`	all	Eliminar una instantánea
`rollback_vm_snapshot`	all	Revertir a una instantánea

Contenedores LXC (11)

Herramienta	Nivel	Descripción
`list_containers`	read	Lista todos los contenedores LXC, opcionalmente filtrados por nodo
`get_container_status`	read	Estado actual del contenedor
`get_container_config`	read	Configuración del contenedor
`list_container_snapshots`	read	Lista todas las instantáneas
`start_container`	lifecycle	Iniciar un contenedor
`stop_container`	lifecycle	Detener forzosamente un contenedor
`shutdown_container`	lifecycle	Apagado elegante con tiempo de espera
`reboot_container`	lifecycle	Reiniciar un contenedor
`create_container_snapshot`	lifecycle	Crear una instantánea
`delete_container_snapshot`	all	Eliminar una instantánea
`rollback_container_snapshot`	all	Revertir a una instantánea

Almacenamiento (2)

Herramienta	Descripción
`list_storage`	Pools de almacenamiento con uso, opcionalmente filtrados por nodo
`get_storage_content`	Contenido de un pool de almacenamiento (ISO, copias de seguridad, imágenes, plantillas)

Clúster (4)

Herramienta	Descripción
`get_cluster_status`	Salud del clúster, quórum, pertenencia de nodos
`get_cluster_resources`	Todos los recursos (VM, contenedores, almacenamiento, nodos)
`get_cluster_backups`	Trabajos de copia de seguridad configurados
`get_next_vmid`	Siguiente ID de VM/contenedor disponible

Arquitectura

src/proxmox_mcp/
├── server.py    # FastMCP instance + entry point
├── config.py    # Pydantic Settings (PROXMOX_ prefix)
├── client.py    # Proxmoxer connection via lifespan
└── tools/       # nodes, vms, containers, storage, cluster

Solo lectura por defecto: herramientas elevadas protegidas por PROXMOX_RISK_LEVEL
Conexión única: cliente Proxmoxer creado una vez al inicio, compartido durante el ciclo de vida
Salida JSON sin procesar: sin formato; el LLM consume los datos directamente

Desarrollo

Ejecutar de forma independiente (pruebas)

export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

docker run -i --rm \
  -e PROXMOX_HOST -e PROXMOX_USER \
  -e PROXMOX_TOKEN_NAME -e PROXMOX_TOKEN_VALUE \
  ghcr.io/akmalovaa/proxmox-mcp:latest

Sin Docker (UV)

git clone https://github.com/akmalovaa/proxmox-mcp.git && cd proxmox-mcp && uv sync

Configuración del cliente MCP:

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "proxmox-mcp"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_NAME": "mcp",
        "PROXMOX_TOKEN_VALUE": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Compilar desde el código fuente

git clone https://github.com/akmalovaa/proxmox-mcp.git
cd proxmox-mcp
docker build -t proxmox-mcp .

Licencia

MIT

proxmox-mcp