Jupyter MCP Server

社区

面向 AI 的 Jupyter Notebook 实时连接与管理 MCP 服务器

分类: 开发工具第 50 / 438
Stars: ★ 1.3k 非常热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Python · Docker · 远程托管（无需本地环境）
凭据: 需要 API Key / 凭据
许可证: BSD-3-Clause
最近提交: 7 天前
工具数: 6

65FMRS · C

Jupyter MCP Server 是一个成熟且文档完善的开源 MCP 服务器，由 Datalayer 维护，专注于让 AI 代理实时操作 Jupyter Notebook。其突出优势是多模态输出、多 Notebook 支持、按单元格输出反馈的执行调整，以及可扩展到十余种云沙箱后端的执行能力。主要需要注意的风险是：代理能够执行任意代码，因此令牌与网络暴露必须谨慎管理；同时 code-sandboxes 与 mcp SDK 的版本配对要求较严格，升级前应核对版本表。

最强项 · 安装易用性 15/20 最弱项 · 可靠性 10/20

可靠性

10/20

安全与权限

12/20

维护活跃度

13/20

文档质量

15/20

安装易用性

15/20

查看各项评分依据

可靠性 10/20: README 描述的路径看似可行：pip/uvx/Docker 三种启动方式、JupyterLab 实时协作预检步骤、以及 pytest tests/ 的测试入口，说明存在一定的可验证路径。但本次仅做静态审查，未缓存任何 server manifest，README 中也没有展示真实的 CI 工作流文件、测试覆盖率或工具 schema（明确说明工具表由在线快照生成而不在仓库内），因此无法核实声明工具与实际行为一致、初始化握手与错误处理是否可控。按静态校准上限 12，且证据缺失应扣分，故给 10。
安全与权限 12/20: 有明确的权限与数据流说明：OAuth 2.1 登录、agent 不接触密码、token 按 notebooks:read/write、code:execute、data:read 作用域收窄、个人访问令牌作为替代方案、Datalayer 权限继续约束可访问的笔记本。风险点在于文档示例使用占位符 MY_TOKEN（未泄露真实凭据），但默认配置要求以 token 启动 Jupyter 并绑定 0.0.0.0，且 code:execute 本质上是任意代码执行；README 未清楚说明危险操作（如执行任意代码、终止 sandbox）是否需要逐次确认。整体主风险可见但确认机制与最小权限的实现细节未在源码中体现，给 12。
维护活跃度 13/20: 维护信号较强：BSD-3-Clause 明确许可、1276 stars、未归档、版本演进记录清晰（v1.3.2 重命名、v1.5.0 沙箱变体、v2.0.0 MCP SDK 2 迁移），并提供 releases、贡献指南与 Discord 社区；32 个未关闭 issue 属正常活跃水平。但本次未见任何 CI 配置、依赖更新策略或安全响应通道（SECURITY.md）的证据，治理与版本兼容性说明多依赖外部站点而非仓库内可审查文件，故按“活跃但治理/版本存在缺口”给 13。
文档质量 15/20: 文档层次丰富：安装（uvx/Docker）、认证（token/OAuth）、参数（JUPYTER_URL、DOCUMENT_ID、SANDBOX_VARIANT 等）、依赖版本对应表（code-sandboxes 与 mcp SDK 兼容矩阵）、沙箱引擎变量表、测试环境变量与最佳实践均有覆盖，并附带外部文档与示例链接。扣分点：工具与参数细节被外链到在线快照而非仓库内可审查，README 未披露成本模型、部分错误排查（如 Unknown sandbox variant）仅点到为止，且关键限制依赖外部页面，静态可核实性不足，故给 15。
安装易用性 15/20: 存在清晰的多路径安装说明：uvx 快速开始、Docker（含 macOS/Windows 与 Linux --network=host 的差异）、以及 JupyterLab 启动命令与 JupyterLab 协作保存行为的验证步骤，客户端 JSON 配置示例完整可复制。扣分点：需要 pip 安装 jupyterlab、jupyter-collaboration、jupyter-mcp-tools、ipykernel 等多个组件，且 code-sandboxes 与 mcp SDK 的版本矩阵容易装错（README 自己记录了装错后首次执行才失败的坑），尚需手动准备 token 与端口；按静态校准上限 15，给 15。

静态评测 · 未实际运行收录于 2026-09-10

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件执行命令或代码

适合谁

已经运行本地 JupyterLab 或 JupyterHub 并希望接入 AI 代理的用户
需要多模态输出（图像、图表、文本）的数据科学与机器学习工作流
希望把代码执行从本地扩展到 Datalayer、Kaggle、Google Colab 等云沙箱的团队
希望保持 Notebook 会话在代理断开后继续运行的用户

不适合谁

不运行任何 Jupyter Server、也不需要 Jupyter Notebook 的用户
使用不支持多模态图像输出的 LLM 或客户端且不希望关闭 ALLOW_IMG_OUTPUT 的用户
希望在无网络或无凭据环境下直接使用云端沙箱变体的用户

所需权限

访问 Jupyter Server 的 URL（JUPYTER_URL / DOCUMENT_URL / CODE_SANDBOX_URL）
Jupyter 访问令牌（JUPYTER_TOKEN，或分别使用 DOCUMENT_TOKEN 与 CODE_SANDBOX_TOKEN）
读写 Notebook 文档与执行代码的权限
使用云端沙箱时需相应厂商的凭据（如 DAYTONA_API_KEY、E2B_API_KEY、CWSANDBOX_API_KEY、CLOUDFLARE_SANDBOX_API_URL / CLOUDFLARE_SANDBOX_API_KEY、Kaggle 凭据、Modal 凭据等）
使用 Datalayer 托管服务时可选 OAuth 2.1 授权范围：notebooks:read、notebooks:write、code:execute、data:read

风险与副作用

AI 代理可在 Notebook 中执行任意代码，可能导致数据泄露、数据损坏或资源滥用
令牌泄露会让持有者获得与令牌同等的 Jupyter 访问权限
JupyterLab 默认以 --ip 0.0.0.0 启动时会扩大网络暴露面
云端沙箱会产生厂商侧的费用，且执行可能超出本地资源限制
jupyter-mcp-server 与 code-sandboxes 版本不匹配时，首次执行会报 Unknown sandbox variant: jupyter

安装接入

准备工作

运行环境：Python · Docker · 远程托管（无需本地环境）

JUPYTER_URL 必填 Jupyter 服务的地址（如 http://localhost:8888），指向你运行的 JupyterLab/Jupyter Server。

JUPYTER_TOKEN 必填密钥 Jupyter 的认证 token，启动时用 --IdentityProvider.token 设置。

DOCUMENT_TOKEN 可选密钥文档服务的独立认证 token。

CODE_SANDBOX_TOKEN 可选密钥代码沙箱服务的认证 token。

DAYTONA_API_KEY 可选密钥使用 Daytona 沙箱引擎所需的 API key，在 Daytona 获取。

E2B_API_KEY 可选密钥使用 E2B 沙箱引擎所需的 API key，在 E2B 获取。

CWSANDBOX_API_KEY 可选密钥使用 CoreWeave 沙箱引擎所需的 API key。

CLOUDFLARE_SANDBOX_API_KEY 可选密钥使用 Cloudflare 沙箱引擎所需的 API key。

其他可选配置项（7 个）

ALLOW_IMG_OUTPUT 可选设为 true 允许返回图片输出；若 LLM 不支持多模态则设为 false。

DOCUMENT_URL 可选单独指定 notebook 文档服务的地址（文档与执行分离部署时使用）。

DOCUMENT_ID 可选默认连接的 notebook 路径，相对于 JupyterLab 启动目录；省略则可交互式选择。

CODE_SANDBOX_URL 可选代码沙箱（如 JupyterHub）服务的地址。

SANDBOX_VARIANT 可选选择沙箱引擎，如 jupyter-server、datalayer、e2b、kaggle 等。

SANDBOX_ENVIRONMENT 可选 Datalayer 等云引擎的环境名称覆盖（例如 ai-agents-env）。

CLOUDFLARE_SANDBOX_API_URL 可选 Cloudflare 沙箱 API 的地址。

准备环境：pip install jupyterlab jupyter-collaboration jupyter-mcp-tools ipykernel。
启动 JupyterLab，例如：jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0。
确认协作功能生效：在 JupyterLab 中打开 Notebook 并编辑任意单元格，观察标签页指示符由 “×” 自动变为 “●”。
配置 MCP 客户端。推荐快速方式使用 uvx（需 uv 0.6.14 或更高）：在客户端配置中写入 command: uvx、args: ["jupyter-mcp-server@latest"]，并设置环境变量 JUPYTER_URL、JUPYTER_TOKEN、ALLOW_IMG_OUTPUT。
生产环境推荐使用 Docker 镜像 datalayer/jupyter-mcp-server:latest，在 macOS/Windows 上使用 host.docker.internal，在 Linux 上使用 --network=host。
如需沙箱生命周期工具或非 jupyter-server 沙箱变体，安装扩展：pip install jupyter_mcp_sandboxes。

claude_desktop_config.json

{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": ["jupyter-mcp-server@latest"],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "jupyter": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server@latest"
      ],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add jupyter -e JUPYTER_URL=http://localhost:8888 -e JUPYTER_TOKEN=MY_TOKEN -e ALLOW_IMG_OUTPUT=true -- uvx jupyter-mcp-server@latest

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在 MCP 客户端连接后，工具列表中应出现 launch_sandbox、list_sandboxes、use_sandbox、terminate_sandbox 等工具；用 list_sandboxes 查询即可证明连接成功。

常见排障

确认 JupyterLab 端口的 JUPYTER_URL 与启动命令中的端口一致
检查 JUPYTER_TOKEN 是否正确，必要时分别设置 DOCUMENT_TOKEN 与 CODE_SANDBOX_TOKEN
确认 jupyter-collaboration 已安装且 Notebook 的未保存指示符会自动变为 “●”
若 LLM 不支持多模态，将 ALLOW_IMG_OUTPUT 设为 false
使用 Docker 时，macOS/Windows 用 host.docker.internal，Linux 用 --network=host
运行 pytest tests/ 验证服务，必要时通过 TEST_MCP_SERVER、TEST_JUPYTER_SERVER 控制测试范围
版本不匹配时按表格配对：jupyter-mcp-server >= 1.5.0 配 code-sandboxes >= 1.1.1，jupyter-mcp-server < 1.5.0 配 code-sandboxes <= 1.0.9
jupyter-mcp-server >= 2.0.0 需要 mcp >= 2，旧版本需要 mcp < 2；环境中有其他包仍锁定 mcp<2 时需留在 jupyter-mcp-server<2

试试这样问

连接成功后，可以直接对 AI 助手这样说：

列出当前可用的 code sandbox
启动一个沙箱并在其中运行一段 Python 代码
运行当前 notebook 的所有单元格
读取当前选中的单元格内容

工具能力 6

launch_sandbox 写入

启动一个代码沙箱（需安装可选的 jupyter_mcp_sandboxes 扩展）。

list_sandboxes 只读

列出当前可用的代码沙箱（需安装可选的 jupyter_mcp_sandboxes 扩展）。

use_sandbox 写入

选择并切换到指定的代码沙箱（需安装可选的 jupyter_mcp_sandboxes 扩展）。

terminate_sandbox 破坏性

终止指定的代码沙箱（需安装可选的 jupyter_mcp_sandboxes 扩展）。

notebook_run-all-cells 写入

运行 Notebook 中的全部单元格（JupyterLab 集成默认暴露的工具，来自 jupyter-mcp-tools）。

notebook_get-selected-cell 只读

获取当前选中的单元格（JupyterLab 集成默认暴露的工具，来自 jupyter-mcp-tools）。

使用场景

让 AI 助手实时读取并修改正在运行的 Jupyter Notebook

让 AI 逐步执行数据分析工作流（数据清洗、特征工程、模型训练、模型评估）

在多个 Notebook 之间切换并管理其内核

生成并查看包含图像和图表的可视化输出

通过沙箱变体把代码执行扩展到云端 GPU 环境

支持客户端

Claude Desktop

Cursor

Windsurf

VS Code

Cline

Claude Code

依据项目文档列出，未经本站实测。

详细介绍

Jupyter MCP Server 是由 Datalayer 开发并维护的 MCP 服务器（BSD 3-Clause 开源许可），用于让 AI 客户端实时连接并操作 Jupyter Notebook。它支持实时查看 Notebook 变化、根据单元格输出反馈智能调整执行、理解整个 Notebook 上下文、处理图像与图表等多模态输出，并可在多个 Notebook 之间切换。服务器兼容任何 MCP 客户端（如 Claude Desktop、Cursor、Windsurf 等），可与本地 Jupyter、JupyterHub 以及 Datalayer 托管 Notebook 配合使用。通过可选的 jupyter_mcp_sandboxes 扩展，代码执行还能切换到 Datalayer、Kaggle、Google Colab、Modal、Daytona、E2B、CoreWeave、Cloudflare 等多种沙箱后端。项目还提供 JupyterLab 集成（默认启用）、jupyter-cite 提示词、OAuth 2.1 登录以及基于 OpenTelemetry 的可观测性。