Slurm HPC MCP 서버

SSH를 통해 Slurm 슈퍼컴퓨팅 클러스터에 연결하고 Claude Desktop, Claude Code, Cursor, MCP Inspector와 같은 클라이언트에 호출 가능한 클러스터 기능을 노출하기 위한 Python 기반 MCP 서버입니다.

현재 버전은 실제 링크 검증을 완료했습니다:

• MCP 서버 정상 시작 가능

• Claude/MCP Inspector 정상 연결 가능

• SSH를 통해 원격 Slurm 로그인 노드에 연결 가능

• 실제 sbatch 작업 제출 가능

• 작업 로그 읽기 가능

• 일반적인 HPC 실행 오류에 대한 구조화된 진단 가능

기능

현재 다음과 같은 MCP 기능을 제공합니다:

• list_jobs 현재 작업 대기열 확인

• list_partitions 파티션 정보 확인

• get_job_status 지정된 작업 상태, 종료 코드, 원인, 로그 경로 조회

• submit_slurm_job Slurm 스크립트 업로드 및 제출

• diagnose_error 로그에 대한 구조화된 오류 분류

• job_log://{job_id} 작업 표준 출력 로그 읽기

Related MCP server: claude-ssh-mcp

기술 스택

• Python

• MCP Python SDK (mcp[cli])

• Paramiko

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

디렉토리 구조

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

설치

독립적인 가상 환경 사용을 권장합니다.

pip install -r requirements.txt

구성 방법

서비스는 환경 변수를 통해 원격 클러스터 구성을 읽습니다.

필수 항목:

• SLURM_SSH_HOST

• SLURM_SSH_USERNAME

선택 항목:

• SLURM_SSH_PORT, 기본값 22

• SLURM_SSH_KEY_PATH

• SLURM_SSH_PASSWORD

• SLURM_SSH_ALLOW_UNKNOWN_HOSTS, 기본값 false

• SLURM_REMOTE_WORKDIR, 기본값 /tmp/mcp-slurm

• SLURM_CONNECT_TIMEOUT, 기본값 15

• SLURM_COMMAND_TIMEOUT, 기본값 60

• SLURM_LOG_MAX_BYTES, 기본값 200000

• MCP_TRANSPORT, 기본값 stdio

로컬 실행

기본적으로 stdio 방식으로 실행되며, Claude Desktop, Claude Code, Cursor, Inspector에 적합합니다:

python .\mcp_hpc_server.py

HTTP 전송으로 전환하려면:

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

Claude Desktop 구성

다음을 참조하십시오:

• claude_desktop_config.example.json

예시:

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

Windows에서 Claude Desktop의 일반적인 구성 위치:

%APPDATA%\Claude\claude_desktop_config.json

MCP Inspector

다음을 참조하십시오:

• mcp.inspector.template.json

Inspector에서 직접 수동으로 구성하는 경우:

• Command에 Python 인터프리터 경로 입력

• Arguments에 mcp_hpc_server.py 경로 입력

• 환경 변수에 SLURM_SSH_* 관련 항목 입력

예제 작업 스크립트

다음을 참조하십시오:

• examples/example_job.slurm

제출 시 클러스터의 실제 상황에 따라 다음을 수정하십시오:

• 파티션 이름

• GRES / GPU / DCU 리소스

• 시간 제한

• 출력 경로

도구 설명

1. list_jobs

현재 대기열에 있는 작업을 확인합니다.

입력:

{
  "user": "optional"
}

2. list_partitions

파티션 상태를 확인합니다.

입력:

{}

3. get_job_status

지정된 작업 상태를 조회합니다.

입력:

{
  "job_id": "37285107"
}

4. submit_slurm_job

Slurm 스크립트를 제출합니다.

입력 필드는 script_content이며, 여러 줄의 스크립트 본문을 직접 입력하십시오. 추가 따옴표로 감싸지 마십시오.

5. diagnose_error

로그 텍스트에 대해 구조화된 장애 분류를 수행합니다.

입력:

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

6. job_log://{job_id}

리소스 템플릿을 통해 작업 표준 출력 로그를 읽습니다.

보안 메커니즘

제출 전 ActionGuard 검사를 거치며, 기본적으로 다음과 같은 위험한 명령을 차단합니다:

• rm -rf /

• mkfs

• /dev/*에 대한 직접 쓰기

• shutdown / reboot

• sudo

이는 첫 번째 방어선일 뿐입니다. 프로덕션 환경에서는 여전히 다음을 권장합니다:

• 권한이 낮은 SSH 계정 사용

• 원격 작업 디렉토리 제한

• 작업 로그 보관

• 개인 키를 저장소에 커밋하지 마십시오

테스트

최소 테스트 실행:

python -m unittest tests.test_mcp_server

현재 최소 테스트 범위:

• 스크립트 첫 줄 검증

• 배치 스크립트 정규화

• 오류 분류 로직

• 파티션 파싱

• 작업 상태 파싱