proxmox-ve-mcp

Un servidor MCP que expone uno o varios hosts Proxmox VE como herramientas que un cliente LLM puede invocar: inventario de nodos, máquinas invitadas, almacenamiento y puentes de red, lectura de estado en vivo, y creación, clonación, inicio, parada y eliminación de VMs y contenedores.

Habla MCP sobre HTTP Streamable, por lo que se ejecuta como su propio servicio en la red en lugar de como un subproceso local de un solo cliente.

Construido para universal-network-director, un gestor de red multi-fabricante impulsado por chat con una puerta de aprobación humana en cada escritura, pero es un servidor MCP independiente y funciona con cualquier cliente MCP.

No está afiliado, respaldado ni soportado por Proxmox Server Solutions GmbH. "Proxmox" y "Proxmox VE" son marcas comerciales de sus respectivos propietarios y se utilizan aquí únicamente para describir con qué se comunica este software.

Lea esto antes de apuntarlo a producción

Doce de las veinticuatro herramientas cambian de estado, y este servidor no pregunta antes de ejecutarlas. No hay confirmación ni simulación. Si un modelo decide invocar una, sucede.

Tres formas de manejar esto, en el orden en que realmente ayudan:

1. Limite el token de API de Proxmox a solo lectura. Este es el control real y reside en Proxmox, no en este código. Asigne al token el rol incorporado PVEAuditor en la ruta / y cada herramienta de escritura fallará en la API sin importar lo que decida cualquier modelo. Haga esto a menos que tenga la intención específica de que las escrituras funcionen.

2. Use la lista de denegación de invitados protegidos. config/protected-vms.json enumera las máquinas invitadas que las herramientas de escritura se niegan a tocar, verificado localmente antes de cualquier llamada al backend, por lo que se mantiene incluso si un humano aprueba algo por accidente. Un archivo faltante o no analizable rechaza cada escritura de invitado en lugar de no proteger nada silenciosamente. Vea abajo.

3. Proteja las escrituras en su cliente. Cada herramienta que cambia de estado tiene el prefijo write_. Ese prefijo es una convención de este código precisamente para que un cliente pueda coincidir con él y enrutar esas llamadas a través de un paso de aprobación humana antes de la ejecución. Este servidor deliberadamente no hace eso por sí mismo — no tiene un usuario al que preguntar.

El endpoint MCP no tiene autenticación

Este servidor expone sus herramientas a cualquiera que pueda alcanzar su puerto. No hay token, ni autenticación de cliente, ni TLS en el lado MCP.

MCP_HOST tiene como valor predeterminado 127.0.0.1 por esa razón. La imagen del contenedor establece 0.0.0.0 porque tiene que hacerlo, lo que significa que publicar el puerto del contenedor coloca un panel de control no autenticado para sus hipervisores en esa interfaz. Manténgalo en una red interna con el cliente, o termine TLS y la autenticación delante de él.

Multi-host por diseño

Los clústeres de Proxmox comparten una API, pero muchas configuraciones ejecutan varios hosts independientes en diferentes subredes sin un clúster entre ellos. Este servidor mantiene una conexión por host, claveada por una etiqueta libre corta, y cada herramienta toma esa etiqueta para elegir con qué host hablar.

Un host se define por un par de variables de entorno:

PROXMOX_SERVER1_URL=https://pve1.example.com:8006
PROXMOX_SERVER1_TOKEN='automation@pve!mcp=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

La <ETIQUETA> en PROXMOX_<ETIQUETA>_URL, en minúsculas, se convierte en el valor host que toman las herramientas (servidor1 arriba). Añada un tercer host añadiendo un tercer par — sin cambio de código. Nómbrelos por el sitio para que el modelo y los registros se lean claramente.

El token es la cadena completa usuario@dominio!tokenid=secreto, que se muestra una vez en la creación en Datacenter → Permisos → Tokens de API. La autenticación es sin estado: cada solicitud lleva un encabezado Authorization: PVEAPIToken=.... No hay llamada de inicio de sesión ni token CSRF — esa es la ruta de sesión de nombre de usuario/contraseña, que este código deliberadamente no utiliza.

Establezca PROXMOX_VERIFY_TLS=false para hosts con certificados autofirmados. El valor predeterminado está activado.

La lista de denegación de invitados protegidos

config/protected-vms.json se monta como solo lectura en el contenedor y contiene las máquinas invitadas que las herramientas de escritura nunca deben tocar:

{
  "protected_vms": [
    {
      "host": "server1",
      "vmid": 100,
      "name": "example-mcp-host",
      "reason": "EXAMPLE -- the VM this MCP server itself runs in"
    }
  ]
}

host es la etiqueta de list_hosts, no el nombre del nodo de Proxmox. reason se muestra textualmente en el rechazo, así que escríbalo para quien lo encuentre.

Este archivo está destinado a ser rastreado en git. Comenzó su vida como una variable de entorno en un .env no rastreado, lo que significaba que la protección no sobrevivía a un clon nuevo y una lista vacía se veía exactamente como una poblada. Ahora, un archivo faltante o no analizable rechaza cada escritura de invitado; una lista vacía está permitida pero registra una advertencia fuerte al inicio.

Las entradas incluidas aquí son ejemplos. Reemplácelas antes de apuntar esto a algo que le importe.

Ejecutarlo

docker build -t proxmox-ve-mcp .
docker run --rm \
  -e PROXMOX_SERVER1_URL=https://pve1.example.com:8006 \
  -e PROXMOX_SERVER1_TOKEN='automation@pve!mcp=...' \
  -e PROXMOX_VERIFY_TLS=false \
  -v "$PWD/config/protected-vms.json:/app/config/protected-vms.json:ro" \
  -p 127.0.0.1:8002:8002 \
  proxmox-ve-mcp

O apunte pip install -r requirements.txt a un virtualenv y ejecute python server.py directamente.

Pruebas

Scripts independientes, sin pytest. Ejecútelos en el contenedor para que tengan el entorno PROXMOX_* que el cliente necesita:

docker run --rm proxmox-ve-mcp python test_network_bridges.py
docker run --rm proxmox-ve-mcp python test_media_in_use.py
docker run --rm proxmox-ve-mcp python test_client.py

Las secciones fuera de línea utilizan listas de interfaces e invitados fabricadas y pasan sin hosts configurados. Las secciones en vivo leen lo que apunten sus variables PROXMOX_* y se omiten limpiamente cuando no hay nada configurado — apúntelos a un host real para ejercitar la única distinción que no se puede falsificar: si un puente está enlazado o aislado.

Notas de diseño

• /cluster/resources es la columna vertebral del inventario. Una llamada devuelve cada VM, contenedor, nodo y almacenamiento ya etiquetado con su nodo, vmid y tipo. Funciona también en un host independiente (informa de ese nodo), por lo que se usa en lugar de recorrer /nodes → /nodes/{node}/qemu por nodo.

• list_network_bridges existe porque una NIC en el puente equivocado es una máquina invitada inalcanzable. Informa, por puente, si tiene un puerto miembro (una salida del servidor) o es un segmento aislado — la distinción que decide si una nueva VM aparece accesible.

• Las etiquetas VLAN fallan de forma segura. Un tag= en un puente que no es bridge_vlan_aware es aceptado por Proxmox y luego no se transporta silenciosamente — tráfico sin etiquetar donde se solicitó aislamiento. Las rutas de escritura rechazan eso en lugar de advertir, y rechazan si no pueden leer la lista de puentes para verificar.

• Las escrituras son asíncronas. La mayoría devuelve un UPID de Proxmox; sondee con get_task_status en lugar de asumir la finalización.

• Las escrituras de invitados se ejecutan detrás de un guardia. Un envoltorio único realiza la verificación de VM protegida y la resolución de vmid→nodo/tipo, por lo que una herramienta individual no puede olvidar el guardia y no puede alcanzar el backend para un invitado protegido.

Licencia

Apache-2.0. Ver LICENSE.