jlab-mcp

A Model Context Protocol (MCP) server that enables Claude Code to execute Python code on GPU compute nodes via JupyterLab running on a SLURM cluster.

Inspired by and adapted from goodfire-ai/scribe, which provides notebook-based code execution for Claude. This project adapts that approach for HPC/SLURM environments where GPU resources are allocated via job schedulers.

Architecture

Claude Code
    ↕ stdio
MCP Server
    ↕ HTTP/WebSocket
JupyterLab (SLURM compute node or local subprocess)   ← one server, many kernels
    ↕
IPython Kernels (GPU access)

JupyterLab runs either on a SLURM compute node (HPC clusters) or as a local subprocess (laptops/workstations). The server process is decoupled from the MCP server and keeps running across Claude Code sessions. It can be started two ways:

• From Claude (recommended): the agent calls the start_server MCP tool, which asks you once whether to run on SLURM or locally (and, for SLURM, the job walltime and resources), launches jlab-mcp start in the background (bootstrapping a bare project with uv init/uv add if needed), then monitors startup with wait_for_server and tells you when it's ready.

• Manually: run jlab-mcp start in a separate terminal.

All sessions create separate kernels on this shared server. Each project directory gets its own JupyterLab instance — the status file is scoped by a hash of the working directory where the server was started.

Related MCP server: Jupyter MCP Server

Local Mode

On machines without SLURM (laptops, workstations), jlab-mcp runs JupyterLab as a local subprocess.

How the mode is chosen:

• Via the start_server MCP tool: on first use in a project it asks you (slurm or local) and saves the choice next to the project's status file (~/.jlab-mcp/servers/{name}-{hash}/run-mode). Pass mode explicitly to change it later.

• Via the CLI (jlab-mcp start): auto-detected — if sbatch is on PATH, SLURM mode; otherwise local mode.

• The JLAB_MCP_RUN_MODE environment variable overrides both:

export JLAB_MCP_RUN_MODE=local   # force local mode
export JLAB_MCP_RUN_MODE=slurm   # force SLURM mode

In local mode, jlab-mcp start runs in the foreground — press Ctrl+C to stop. The status file uses the same format as SLURM mode, so the MCP server works identically in both modes.

Setup

Zero-install (recommended)

The only prerequisites are Claude Code and uv. Drop this .mcp.json into any project directory — uvx fetches and runs jlab-mcp on demand (cached after the first run), no separate install step:

{
  "mcpServers": {
    "jlab-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kdkyum/jlab-mcp.git", "jlab-mcp"]
    }
  }
}

Start Claude Code in that directory and approve the MCP server when prompted. The first launch clones and builds the package, so it can take a little longer; pin a tag (git+...@v1.0.2) for reproducibility.

Pre-installed alternative

For faster MCP startup (or offline login nodes), install the CLI once and reference it directly:

uv tool install git+https://github.com/kdkyum/jlab-mcp.git

The SLURM job activates .venv in the current working directory. If the project has no environment yet (e.g. a fresh directory with just .mcp.json), start_server bootstraps it automatically (uv init --bare + uv add jupyterlab ipykernel matplotlib numpy). To set it up manually, or to add GPU-enabled torch:

cd /shared/fs/my-project
uv venv
uv pip install jupyterlab ipykernel matplotlib numpy
uv pip install torch --index-url https://download.pytorch.org/whl/cu126   # NVIDIA GPUs
# AMD GPUs (e.g. MI300A): use the ROCm wheels instead
# uv pip install torch --index-url https://download.pytorch.org/whl/rocm6.3

Usage

Option A: Let Claude manage the server

Just start Claude Code in your project directory and ask it to run something in a notebook. When no server is running, the agent calls start_server (asking you SLURM vs local on first use), waits in the background via wait_for_server, and reports when JupyterLab is ready. To stop the server, ask Claude or run jlab-mcp stop.

Option B: Manual CLI

1. Start the compute node

In a separate terminal, start the SLURM job:

jlab-mcp start              # uses default time limit (4h)
jlab-mcp start 24:00:00     # 24 hour time limit
jlab-mcp start 1-00:00:00   # 1 day

This submits the job and waits until JupyterLab is ready:

SLURM job 24215408 submitted, waiting in queue...
Job running on ravg1011, JupyterLab starting...
JupyterLab ready at http://ravg1011:18432

2. Use Claude Code

In another terminal, start Claude Code. The MCP server connects to the running JupyterLab automatically.

3. Stop when done

jlab-mcp stop

CLI Commands

All commands accept --debug to enable verbose logging (status file reads, SLURM parameters, health check attempts, connection file paths) on stderr.

The SLURM job survives Claude Code restarts. You only need to run jlab-mcp start once per work session.

Configuration

All settings are configurable via environment variables. No values are hardcoded for a specific cluster.

Example: Cluster with A100 GPUs and CUDA module

export JLAB_MCP_SLURM_PARTITION=gpu1
export JLAB_MCP_SLURM_GRES=gpu:a100:1
export JLAB_MCP_SLURM_CPUS=18
export JLAB_MCP_SLURM_MEM=125000
export JLAB_MCP_SLURM_TIME=1-00:00:00
export JLAB_MCP_SLURM_MODULES="cuda/12.6"

Claude Code Integration

Use the zero-install .mcp.json from Setup, or — with the CLI pre-installed — reference the binary directly in ~/.claude.json or a project .mcp.json:

{
  "mcpServers": {
    "jlab-mcp": {
      "command": "jlab-mcp"
    }
  }
}

No env block is needed: on first use the agent surveys the cluster (sinfo) and asks you for walltime and resources, saving the choices per project. An env block with JLAB_MCP_* variables still works to pin cluster-specific defaults (e.g. JLAB_MCP_SLURM_MODULES for a CUDA module).

The MCP server uses the working directory to find .venv for the compute node. Claude Code launches from your project directory, so it picks up the right venv automatically.

MCP Tools

Resource: jlab-mcp://server/status — returns shared server info and active sessions.

Session Lifecycle

• start_new_notebook: Creates a new kernel and a new notebook. Any previously running kernels/sessions are shut down (one active session at a time)

• start_notebook: Opens an existing notebook. If a session with a live kernel already exists for it, that session is returned with all state preserved; otherwise a fresh kernel is started

• Restart kernel: shutdown_session + start_notebook(same_path) = fresh kernel on same notebook

• shutdown_session: Kills the kernel only. The SLURM job keeps running.

• SLURM job dies: Next tool call returns an error pointing the agent at start_server (or run jlab-mcp start manually).

Testing

# Unit tests (no SLURM needed)
uv run python -m pytest tests/ --ignore=tests/test_tools.py -v

# Integration tests (requires running `jlab-mcp start` first)
uv run python -m pytest tests/test_tools.py -v -s --timeout=600

Acknowledgments

This project is inspired by goodfire-ai/scribe, which provides MCP-based notebook code execution for Claude. The tool interface design, image resizing approach, and notebook management patterns are adapted from scribe for use on HPC/SLURM clusters.

License

MIT