Servidor MCP para Slurm HPC

Un servidor MCP basado en Python para conectar con clústeres de supercomputación Slurm a través de SSH y exponer capacidades del clúster a clientes como Claude Desktop, Claude Code, Cursor, MCP Inspector, entre otros.

La versión actual ha completado la validación del enlace real:

• El servidor MCP se inicia correctamente

• Claude/MCP Inspector se conecta correctamente

• Se puede conectar a nodos de inicio de sesión remotos de Slurm mediante SSH

• Se pueden enviar trabajos sbatch reales

• Se pueden leer los registros (logs) de los trabajos

• Se puede realizar un diagnóstico estructurado de errores comunes de ejecución en HPC

Funcionalidades

Actualmente se ofrecen las siguientes capacidades MCP:

• list_jobs Ver la cola de trabajos actual

• list_partitions Ver información de las particiones

• get_job_status Consultar el estado, código de salida, motivo y ruta de registro de un trabajo específico

• submit_slurm_job Subir y enviar un script de Slurm

• diagnose_error Realizar una clasificación estructurada de errores en los registros

• job_log://{job_id} Leer el registro de salida estándar del trabajo

Related MCP server: claude-ssh-mcp

Stack tecnológico

• Python

• MCP Python SDK (mcp[cli])

• Paramiko

• Slurm CLI (squeue, sinfo, sacct, scontrol, sbatch)

Estructura de directorios

slurm-hpc-mcp/
├─ mcp_hpc_server.py
├─ README.md
├─ requirements.txt
├─ claude_desktop_config.example.json
├─ mcp.inspector.template.json
├─ examples/
│  └─ example_job.slurm
└─ tests/
   └─ test_mcp_server.py

Instalación

Se recomienda utilizar un entorno virtual independiente.

pip install -r requirements.txt

Configuración

El servicio lee la configuración del clúster remoto a través de variables de entorno.

Obligatorias:

• SLURM_SSH_HOST

• SLURM_SSH_USERNAME

Opcionales:

• SLURM_SSH_PORT, por defecto 22

• SLURM_SSH_KEY_PATH

• SLURM_SSH_PASSWORD

• SLURM_SSH_ALLOW_UNKNOWN_HOSTS, por defecto false

• SLURM_REMOTE_WORKDIR, por defecto /tmp/mcp-slurm

• SLURM_CONNECT_TIMEOUT, por defecto 15

• SLURM_COMMAND_TIMEOUT, por defecto 60

• SLURM_LOG_MAX_BYTES, por defecto 200000

• MCP_TRANSPORT, por defecto stdio

Ejecución local

Por defecto se ejecuta mediante stdio, adecuado para Claude Desktop, Claude Code, Cursor e Inspector:

python .\mcp_hpc_server.py

Si desea cambiar a transporte HTTP:

$env:MCP_TRANSPORT="streamable-http"
python .\mcp_hpc_server.py

Configuración de Claude Desktop

Por favor, consulte:

• claude_desktop_config.example.json

Ejemplo:

{
    "mcpServers": {
      "slurm-hpc": {
        "type": "stdio",
        "command": "<your-python-executable>",
        "args": ["<your-project-dir>/mcp_hpc_server.py"],
        "env": {
        "SLURM_SSH_HOST": "your-login-host",
        "SLURM_SSH_PORT": "22",
        "SLURM_SSH_USERNAME": "your-username",
        "SLURM_SSH_KEY_PATH": "<your-ssh-private-key-path>",
        "SLURM_SSH_ALLOW_UNKNOWN_HOSTS": "true"
      }
    }
  }
}

Ubicaciones comunes de configuración de Claude Desktop en Windows:

%APPDATA%\Claude\claude_desktop_config.json

MCP Inspector

Por favor, consulte:

• mcp.inspector.template.json

Si configura manualmente en el Inspector:

• En Command introduzca la ruta del intérprete de Python

• En Arguments introduzca la ruta de mcp_hpc_server.py

• En las variables de entorno, introduzca los elementos relacionados con SLURM_SSH_*

Ejemplo de script de trabajo

Consulte:

• examples/example_job.slurm

Al enviar, modifique según las condiciones reales de su clúster:

• Nombre de la partición

• Recursos GRES / GPU / DCU

• Límite de tiempo

• Ruta de salida

Descripción de herramientas

1. list_jobs

Ver los trabajos en la cola actual.

Entrada:

{
  "user": "optional"
}

2. list_partitions

Ver el estado de las particiones.

Entrada:

{}

3. get_job_status

Consultar el estado de un trabajo específico.

Entrada:

{
  "job_id": "37285107"
}

4. submit_slurm_job

Enviar un script de Slurm.

El campo de entrada es script_content, introduzca directamente el cuerpo del script multilínea, sin añadir comillas adicionales.

5. diagnose_error

Realizar una clasificación estructurada de fallos en el texto del registro.

Entrada:

{
  "log_content": "ModuleNotFoundError: No module named 'mpi4py'"
}

6. job_log://{job_id}

Leer el registro de salida estándar del trabajo a través de la plantilla de recursos.

Mecanismos de seguridad

Antes del envío, se realiza una comprobación mediante ActionGuard, que bloquea por defecto comandos peligrosos típicos, tales como:

• rm -rf /

• mkfs

• Escritura directa en /dev/*

• shutdown / reboot

• sudo

Esta es solo la primera capa de protección. Para entornos de producción, se recomienda:

• Utilizar una cuenta SSH con privilegios bajos

• Limitar el directorio de trabajo remoto

• Conservar los registros de operaciones

• No subir claves privadas al repositorio

Pruebas

Ejecutar las pruebas mínimas:

python -m unittest tests.test_mcp_server

Las pruebas mínimas actuales cubren:

• Validación de la primera línea del script

• Normalización de scripts por lotes

• Lógica de clasificación de errores

• Análisis de particiones

• Análisis de estado de trabajos