Slurm HPC MCP Server

A Python-based MCP Server designed to connect to Slurm HPC clusters via SSH and expose cluster capabilities to clients such as Claude Desktop, Claude Code, Cursor, and MCP Inspector.

The current version has completed full-path verification:

• MCP Server starts successfully

• Claude/MCP Inspector connects successfully

• Can connect to remote Slurm login nodes via SSH

• Can submit real sbatch jobs

• Can read job logs

• Can perform structured diagnosis for common HPC runtime errors

Features

The following MCP capabilities are currently provided:

• list_jobs View the current job queue

• list_partitions View partition information

• get_job_status Query the status, exit code, reason, and log path of a specific job

• submit_slurm_job Upload and submit a Slurm script

• diagnose_error Perform structured error classification on logs

• job_log://{job_id} Read job standard output logs

Related MCP server: claude-ssh-mcp

Tech Stack

• Python

• MCP Python SDK (mcp[cli])

• Paramiko

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

Directory Structure

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

Using an independent virtual environment is recommended.

pip install -r requirements.txt

Configuration

The service reads remote cluster configuration via environment variables.

Required:

• SLURM_SSH_HOST

• SLURM_SSH_USERNAME

Optional:

• SLURM_SSH_PORT, default 22

• SLURM_SSH_KEY_PATH

• SLURM_SSH_PASSWORD

• SLURM_SSH_ALLOW_UNKNOWN_HOSTS, default false

• SLURM_REMOTE_WORKDIR, default /tmp/mcp-slurm

• SLURM_CONNECT_TIMEOUT, default 15

• SLURM_COMMAND_TIMEOUT, default 60

• SLURM_LOG_MAX_BYTES, default 200000

• MCP_TRANSPORT, default stdio

Running Locally

By default, it runs in stdio mode, which is suitable for Claude Desktop, Claude Code, Cursor, and Inspector:

python .\mcp_hpc_server.py

To switch to HTTP transport:

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

Claude Desktop Configuration

Please refer to:

• claude_desktop_config.example.json

Example:

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

Common configuration location for Claude Desktop on Windows:

%APPDATA%\Claude\claude_desktop_config.json

MCP Inspector

Please refer to:

• mcp.inspector.template.json

If you configure it manually in Inspector:

• Set Command to the Python interpreter path

• Set Arguments to the mcp_hpc_server.py path

• Set environment variables for SLURM_SSH_* related items

Example Job Script

Refer to:

• examples/example_job.slurm

When submitting, please modify the following according to your cluster's actual situation:

• Partition name

• GRES / GPU / DCU resources

• Time limit

• Output path

Tool Descriptions

1. list_jobs

View jobs in the current queue.

Input:

{
  "user": "optional"
}

2. list_partitions

View partition status.

Input:

{}

3. get_job_status

Query the status of a specific job.

Input:

{
  "job_id": "37285107"
}

4. submit_slurm_job

Submit a Slurm script.

The input field is script_content; enter the multi-line script body directly without extra quotes.

5. diagnose_error

Perform structured fault classification on log text.

Input:

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

6. job_log://{job_id}

Read job standard output logs via resource template.

Security Mechanisms

Submissions are checked by ActionGuard before execution, which blocks typical dangerous commands by default, such as:

• rm -rf /

• mkfs

• Direct writes to /dev/*

• shutdown / reboot

• sudo

This is only the first layer of protection. For production environments, it is still recommended to:

• Use a low-privilege SSH account

• Restrict the remote working directory

• Retain operation logs

• Do not commit private keys to the repository

Testing

Run minimal tests:

python -m unittest tests.test_mcp_server

Current minimal test coverage:

• Script shebang validation

• Batch script normalization

• Error classification logic

• Partition parsing

• Job status parsing