Proxmox Monitoring MCP Server

Monitoreo de solo lectura y auditoría de configuración para el clúster IaaS de Proxmox, servido a Claude a través de MCP. Se ejecuta localmente sobre stdio; no hay ninguna ruta de escritura en este paquete (proxmox_mcp/client.py solo implementa GET), y el token de API usa el rol PVEAuditor para que Proxmox mismo aplique el modo de solo lectura.

1. Crear el token de API en Proxmox (una vez, como root en cualquier nodo)

pveum user add claude-monitor@pve --comment "Read-only MCP monitoring"
pveum acl modify / --users claude-monitor@pve --roles PVEAuditor
pveum user token add claude-monitor@pve mcp --privsep 1
pveum acl modify / --tokens 'claude-monitor@pve!mcp' --roles PVEAuditor

El comando token add imprime el secreto una sola vez: cópialo inmediatamente. Con separación de privilegios (--privsep 1), los derechos efectivos del token son la intersección de las ACL del usuario y del token, por lo que PVEAuditor debe otorgarse a ambos (el cuarto comando es el que todos olvidan).

Equivalente en la GUI: Datacenter → Permissions → Users → Add; Datacenter → Permissions → API Tokens → Add; luego Datacenter → Permissions → Add → tanto un User Permission como un API Token Permission en la ruta /, rol PVEAuditor, con Propagate activado.

Related MCP server: proxmox-mcp

2. Configurar e instalar (esta máquina)

cd <your-workspace>/proxmox-mcp
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
cp .env.example .env    # then fill in PROXMOX_HOST / TOKEN_ID / TOKEN_SECRET

3. Registrar con Claude Code

claude mcp add proxmox --scope user -- <your-workspace>/proxmox-mcp/.venv/Scripts/python.exe <your-workspace>/proxmox-mcp/run_server.py

Herramientas

config_audit verifica: cobertura de respaldo, instantáneas obsoletas, almacenamiento >85%, memoria de nodo >90%, sobrecompromiso de memoria >1.5x, sobrecompromiso de CPU >4x, desviación de versión de PVE entre nodos, tipo de CPU predeterminado kvm64, agente invitado deshabilitado, discos en el bus IDE y tareas que fallaron en las últimas 48h. Los umbrales son ajustables en .env.

Tres prompts de MCP se incluyen con el servidor (visibles en claude.ai bajo "Add from proxmox-monitor"): Cluster Config Audit, Cluster Health Brief, Backup Coverage Check.

Sirviéndolo al equipo (remoto, autenticado con Entra)

El servidor es de doble transporte. MCP_TRANSPORT=stdio (predeterminado) es para Claude Code local; MCP_TRANSPORT=http sirve HTTP transmisible con autenticación de Microsoft Entra ID en modo servidor de recursos, según ~/.claude/context/mcp-server-playbook.md.

• Entra: scripts/setup_entra_app.ps1 aprovisiona la aplicación, el alcance access_as_user, ambas URI de redirección de Claude, tokens v2, el secreto de cliente y el grupo de seguridad Proxmox-MCP-Users con sus miembros. Ejecútalo con -ResolveOnly primero para verificar que la lista de compañeros se resuelve. Detalles y el respaldo manual: docs/ENTRA_SETUP_CHECKLIST.md.

• Despliegue: puerto de host 8119 en 10.0.0.10, nombre de host público proxmox-mcp.example.com. Pasos, variables de stack y configuración del host proxy NPM: PORTAINER_DEPLOY.md.

El despliegue está bloqueado hasta que se realice el mantenimiento de default-address-pools del host de Docker: está en 31/31 redes, por lo que cualquier stack nuevo falla al crearse. El registro de Entra se puede hacer ahora; el servidor stdio sigue funcionando mientras tanto.

Pruebas

<your-workspace>/proxmox-mcp/.venv/Scripts/python.exe -m pytest tests -q

No necesitan conexión con Proxmox. Verifican que cada herramienta y prompt esté registrado, que cada prompt nombre su propio conector (el vocabulario choca entre una docena de conectores adjuntos), que ProxmoxClient no haya adquirido ningún método mutador y que la autenticación se niegue a iniciar si está a medio configurar.