Jlab

This MCP server enables Claude Code to run Python code on GPU compute nodes by launching a JupyterLab session on a SLURM cluster and coordinating kernels through a shared file system. It streamlines GPU-accelerated code execution in HPC environments by submitting a single SLURM job that hosts JupyterLab, with multiple user sessions creating individual kernels on that shared server.

How to use

You will interact with the MCP server through Claude Code, which communicates with the MCP server to start and manage Python execution kernels on the SLURM-backed compute node. A single SLURM job hosts JupyterLab, and each user session creates a separate kernel on that shared server. Connection details for the shared server are exchanged via files on the shared filesystem.

Typical usage patterns include starting a new session to obtain a kernel, resuming a notebook to restore previous state, forking a notebook to try a different exploration with a fresh kernel, executing code cells, editing cells, adding markdown, and shutting down kernels when you are done. The SLURM job keeps running for other sessions, and the system automatically recreates a SLURM job if the compute node or slot becomes unavailable. Session information is exposed through a shared server status endpoint.

Before you begin, ensure your project saves dependencies in a shared filesystem location and that you have a working virtual environment compatible with the compute node. The MCP server will activate the project’s virtual environment when the SLURM job starts, enabling GPU-accelerated libraries like PyTorch to be used in the compute node’s JupyterLab kernels.

How to install

Prerequisites you need on your workstation or head node where Claude Code runs:

• Node.js and uv tooling installed on your machine
• Python and pip available for local tooling if needed
• Access to a shared filesystem mounted from both login and compute nodes

Install the MCP server package directly from its source without cloning a repository first:

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

Configuration and runtime notes

The SLURM job created by the MCP server activates a Python virtual environment located in the current working directory. Set up your project’s virtual environment in the shared filesystem with the compute dependencies before starting the server. You typically install your project dependencies once in the shared workspace and reuse them for all sessions.

Main environment variables control the SLURM submission details, ports, and paths. You can adjust these to match your cluster’s partitions and resources. The MCP server uses a single SLURM job to host JupyterLab on a compute node, and all user sessions create kernels on that shared server.

MCP server command and environment

The MCP server is launched as a local, stdio-based server. Use the provided runtime command and environment to start it from your project directory. The server accepts configuration through environment variables and starts a background SLURM job to provide compute resources.

{
  "mcpServers": {
    "jlab_mcp": {
      "command": "jlab-mcp",
      "env": {
        "JLAB_MCP_SLURM_PARTITION": "gpu1",
        "JLAB_MCP_SLURM_GRES": "gpu:a100:1",
        "JLAB_MCP_SLURM_MODULES": "cuda/12.6"
      }
    }
  }
}

Available tools

start_new_session

Start a new kernel on the shared server and create an empty notebook for execution.

start_session_resume_notebook

Resume an existing notebook by re-executing all cells to restore prior state.

start_session_continue_notebook

Fork a notebook with a fresh kernel without re-executing cells.

execute_code

Run Python code in the active kernel and append output to the notebook, returning text and image results.

edit_cell

Edit a cell and re-execute it, supporting negative indexing for convenience.

add_markdown

Insert a markdown cell into the notebook for documentation or notes.

shutdown_session

Stop the active kernel while keeping the SLURM job running for other sessions.