Slurm HPC MCP Server

Ein Python-basierter MCP-Server, der dazu dient, über SSH eine Verbindung zu Slurm-HPC-Clustern herzustellen und aufrufbare Cluster-Funktionen für Clients wie Claude Desktop, Claude Code, Cursor und den MCP Inspector bereitzustellen.

Die aktuelle Version hat die Validierung der echten Kette abgeschlossen:

• MCP-Server kann normal gestartet werden

• Claude/MCP Inspector kann normal eine Verbindung herstellen

• Verbindung zu entfernten Slurm-Login-Knoten via SSH möglich

• Echte sbatch-Jobs können eingereicht werden

• Job-Logs können gelesen werden

• Strukturierte Diagnose für häufige HPC-Laufzeitfehler möglich

Funktionen

Derzeit werden folgende MCP-Fähigkeiten bereitgestellt:

• list_jobs Anzeigen der aktuellen Job-Warteschlange

• list_partitions Anzeigen von Partitionsinformationen

• get_job_status Abfragen von Status, Exit-Code, Grund und Log-Pfad eines bestimmten Jobs

• submit_slurm_job Hochladen und Einreichen von Slurm-Skripten

• diagnose_error Strukturierte Fehlerklassifizierung für Logs

• job_log://{job_id} Lesen des Standard-Ausgabe-Logs eines Jobs

Related MCP server: claude-ssh-mcp

Technischer Stack

• Python

• MCP Python SDK (mcp[cli])

• Paramiko

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

Verzeichnisstruktur

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

Installation

Es wird empfohlen, eine separate virtuelle Umgebung zu verwenden.

pip install -r requirements.txt

Konfiguration

Der Dienst liest die Konfiguration des entfernten Clusters über Umgebungsvariablen.

Erforderlich:

• SLURM_SSH_HOST

• SLURM_SSH_USERNAME

Optional:

• SLURM_SSH_PORT, Standard 22

• SLURM_SSH_KEY_PATH

• SLURM_SSH_PASSWORD

• SLURM_SSH_ALLOW_UNKNOWN_HOSTS, Standard false

• SLURM_REMOTE_WORKDIR, Standard /tmp/mcp-slurm

• SLURM_CONNECT_TIMEOUT, Standard 15

• SLURM_COMMAND_TIMEOUT, Standard 60

• SLURM_LOG_MAX_BYTES, Standard 200000

• MCP_TRANSPORT, Standard stdio

Lokale Ausführung

Standardmäßig erfolgt die Ausführung über stdio, was für Claude Desktop, Claude Code, Cursor und den Inspector geeignet ist:

python .\mcp_hpc_server.py

Für den Wechsel auf HTTP-Transport:

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

Claude Desktop Konfiguration

Bitte beachten Sie:

• claude_desktop_config.example.json

Beispiel:

{
    "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"
      }
    }
  }
}

Typische Konfigurationspfade für Claude Desktop unter Windows:

%APPDATA%\Claude\claude_desktop_config.json

MCP Inspector

Bitte beachten Sie:

• mcp.inspector.template.json

Wenn Sie die Konfiguration direkt im Inspector manuell vornehmen:

• Command: Pfad zum Python-Interpreter

• Arguments: Pfad zu mcp_hpc_server.py

• Umgebungsvariablen: SLURM_SSH_* relevante Einträge

Beispiel-Job-Skript

Siehe:

• examples/example_job.slurm

Bitte passen Sie beim Einreichen die Werte an Ihre tatsächliche Cluster-Umgebung an:

• Partitionsname

• GRES / GPU / DCU Ressourcen

• Zeitlimit

• Ausgabepfad

Tool-Beschreibung

1. list_jobs

Anzeigen der Jobs in der aktuellen Warteschlange.

Eingabe:

{
  "user": "optional"
}

2. list_partitions

Anzeigen des Partitionsstatus.

Eingabe:

{}

3. get_job_status

Abfragen des Status eines bestimmten Jobs.

Eingabe:

{
  "job_id": "37285107"
}

4. submit_slurm_job

Einreichen eines Slurm-Skripts.

Das Eingabefeld ist script_content; geben Sie den Inhalt des mehrzeiligen Skripts direkt ein, ohne zusätzliche Anführungszeichen.

5. diagnose_error

Strukturierte Fehlerklassifizierung für Log-Texte.

Eingabe:

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

6. job_log://{job_id}

Lesen des Standard-Ausgabe-Logs eines Jobs über eine Ressourcen-Vorlage.

Sicherheitsmechanismen

Vor dem Einreichen erfolgt eine Prüfung durch ActionGuard, die standardmäßig typische gefährliche Befehle blockiert, wie zum Beispiel:

• rm -rf /

• mkfs

• Direktes Schreiben auf /dev/*

• shutdown / reboot

• sudo

Dies ist nur die erste Schutzschicht. Für Produktionsumgebungen wird weiterhin empfohlen:

• Verwendung eines SSH-Kontos mit niedrigen Berechtigungen

• Einschränkung des entfernten Arbeitsverzeichnisses

• Aufbewahrung von Betriebsprotokollen

• Keine privaten Schlüssel in Repositories hochladen

Testen

Minimalen Test ausführen:

python -m unittest tests.test_mcp_server

Aktuelle Abdeckung der minimalen Tests:

• Validierung der ersten Skriptzeile

• Normalisierung von Batch-Skripten

• Fehlerklassifizierungslogik

• Partitionsanalyse

• Job-Status-Analyse