Skip to main content
Glama
proxmox-monitor

proxmox-monitor

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: pve-mcp-server

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

Herramienta

Qué responde

capabilities

"¿Qué puede hacer esto?"

cluster_health

Quórum, estado de nodos, resumen de CPU/memoria

list_nodes / node_status

Detalle por host, versiones, carga

list_guests / guest_config

Inventario de VM/LXC y configuraciones completas

storage_status

Cada almacén de datos con uso

backup_status

Trabajos de respaldo + invitados cubiertos por ningún trabajo

snapshot_audit

Todas las instantáneas con antigüedad y indicador de estado de RAM

recent_tasks

Tareas recientes del clúster fallidas (o todas)

pending_updates

Paquetes pendientes de instalación por nodo

config_audit

Insignia — cada verificación a continuación, calificada como advertencia/información

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server for Proxmox VE that provides AI assistants with structured visibility into cluster nodes, guests, storage, and Docker workloads. It is designed to prevent any mutating operations by construction.
      12
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      Read-only Proxmox VE MCP server providing 25 tools for VM, LXC, node, storage, and cluster inspection via stdio transport.
      25
      -