jlab MCP

jlab mcp

A. 模型上下文协议（MCP） 该服务器使Claude Code能够通过在SLURM集群上运行的JupyterLab在GPU计算节点上执行Python代码。

灵感来自并改编自 goodfire ai/抄写员，为Claude提供基于笔记本电脑的代码执行。该项目将这种方法应用于HPC/SLURM环境，其中GPU资源是通过作业调度器分配的。

建筑

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

JupyterLab可以在SLURM计算节点（HPC集群）上运行，也可以作为本地子进程（笔记本电脑/工作站）运行。服务器与MCP服务器分开管理——您可以从以下位置启动它 jlab-mcp start 并且它一直在Claude Code会话中运行。所有会话在此共享服务器上创建单独的内核。每个项目目录都有自己的JupyterLab实例——状态文件的作用域由工作目录的哈希值决定，其中 jlab-mcp start 被运行。

本地模式

在没有SLURM的机器上（笔记本电脑、工作站），jlab-mcp会自动将JupyterLab作为本地子进程运行。模式自动检测：如果 sbatch 在PATH上，使用SLURM模式；否则为本地模式。

用环境变量覆盖：

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

在本地模式下， jlab-mcp start 跑步在 前景 --按Ctrl+C停止。状态文件使用与SLURM模式相同的格式，因此MCP服务器在这两种模式下的工作方式相同。

设置

# Install (no git clone needed)
uv tool install git+https://github.com/kdkyum/jlab-mcp.git

SLURM作业激活 .venv 在 当前工作目录.使用计算依赖关系在共享文件系统上设置项目的venv：

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  # GPU support

用法

1.启动计算节点

在单独的终端中，启动SLURM作业：

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

这将提交作业并等待JupyterLab准备就绪：

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

2.使用克劳德代码

在另一个终端中，启动Claude Code。MCP服务器自动连接到正在运行的JupyterLab。

3.完成后停止

jlab-mcp stop

CLI命令

所有命令接受 --debug 在stderr上启用详细日志记录（状态文件读取、SLURM参数、健康检查尝试、连接文件路径）。

SLURM工作 幸存克劳德代码重启你只需要跑 jlab-mcp start 每次工作会议一次。

配置

所有设置都可以通过环境变量进行配置。特定集群没有硬编码值。

示例：使用A100 GPU和CUDA模块的集群

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代码集成

添加 ~/.claude.json 或项目 .mcp.json:

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

MCP服务器使用工作目录查找 .venv 对于计算节点。Claude Code从您的项目目录启动，因此它会自动选择正确的venv。

MCP工具

资源： jlab-mcp://server/status --返回共享服务器信息和活动会话。

会话生命周期

• start_new_notebook：创建新内核和新笔记本
• start_notebook：将新内核附加到现有笔记本
• 重新启动内核: shutdown_session + start_notebook(same_path) =同一笔记本电脑上的新内核
• shutdown_session：仅杀死内核。SLURM作业继续运行。
• SLURM工作死亡：下一个工具调用返回错误。跑 jlab-mcp start 重新启动。

测试

# Unit tests (no SLURM needed)
uv run python -m pytest tests/test_slurm.py tests/test_notebook.py tests/test_image_utils.py -v

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

致谢

这个项目的灵感来自 goodfire ai/抄写员，为Claude提供基于MCP的笔记本代码执行。工具界面设计、图像大小调整方法和笔记本管理模式都改编自scribe，用于HPC/SLURM集群。

许可证

麻省理工学院