🪐✨ Jupyter MCP Server

📖 文档  ·  🔧 工具  ·  💬 社区

无需运行进程。 Datalayer 现在为你托管此服务，地址为 https://mcp.datalayer.run/mcp —— 一个端点，适用于每个 Agent 和每个 Notebook。 通过浏览器登录，批准 Agent 可以执行的操作；即使 Agent 断开连接，你的工作也会继续在服务器上运行。

→ 托管的 Jupyter MCP 服务

只需一条命令即可连接 Claude Code，并提供 /datalayer:notebook、/datalayer:run 和 /datalayer:status：

/plugin marketplace add datalayer/jupyter-mcp-server
/plugin install datalayer

→ Claude Code 的 Datalayer 插件

免费开源，采用 BSD 3-Clause 许可证 —— 可连接你已在运行的任何 Jupyter，无论是本地环境还是 JupyterHub，无需账户。

由 Datalayer 构建和维护。同一服务还驱动始终在线的 Notebook，配备 GPU 代码沙盒和持久化执行功能——即使你的笔记本电脑不在身边，Agent 也能继续处理你的数据。

无需复制粘贴令牌。 当 Agent 未经身份验证连接到此服务时，它会收到身份验证位置的提示，打开你的浏览器，你以自己的身份登录 Datalayer。Agent 永远看不到你的密码——它会收到一个令牌，其权限范围仅限于你批准的内容；你可以断开某个 Agent，而不影响其他 Agent。

每个 Agent 可以执行哪些操作，由两个独立的决策决定：你批准的权限范围（notebooks:read、notebooks:write、code:execute、data:read）决定它可以执行哪类操作，而你自己的 Datalayer 权限仍决定它可以访问哪些笔记本。Agent 永远无法访问你无权访问的笔记本。

个人访问令牌仍可使用，对于 CLI 或脚本来说依然是更简单的选择。 → OAuth 和身份

将 code-sandboxes 固定到与 jupyter-mcp-server 匹配的版本。 code-sandboxes 1.1.1 将沙箱变体 jupyter 重命名为 jupyter-server，两个包必须使用相同的名称。

# On 1.5.0 or later
pip install "jupyter-mcp-server>=1.5.0" "code-sandboxes>=1.1.1"

# Staying on an earlier jupyter-mcp-server
pip install "jupyter-mcp-server<1.5.0" "code-sandboxes<=1.0.9"

较旧的服务搭配较新的 code-sandboxes 可以顺利安装，但首次执行时会因 Unknown sandbox variant: jupyter 而失败。 → 发行说明

Jupyter MCP Server 2 基于 MCP Python SDK 2（mcp>=2,<3）运行，这是该 SDK 的首个主版本。启动或配置服务、使用工具，以及连接到该服务的 MCP 客户端，方式均没有变化——协议仍会像以前一样与每个客户端协商。变化之处在于 Python 环境：

这两个依赖均已在包中固定，因此 pip 会处理好；如果某个环境中有其他包仍固定使用 mcp<2，那么在该包升级之前，必须继续使用 jupyter-mcp-server<2。如果你要基于 SDK 编写扩展或自定义令牌验证器，请参阅发行说明了解重命名后的导入项。

--provider 现已更名为 --document-provider（环境变量 PROVIDER → DOCUMENT_PROVIDER）。

它过去一直只用于选择笔记本文档的存放位置——jupyter 表示使用 Jupyter Server 的协作 API，datalayer 表示使用 Datalayer spacer——而旧名称及其帮助文本却让人以为它也能选择代码的运行位置。执行环境通过 --sandbox-variant 单独选择（jupyter-server、datalayer、daytona、e2b、coreweave、cloudflare、kaggle、google-colab、monty、modal）。

v1.3.2 不会造成任何兼容性问题：仍接受 --provider 作为别名，仍会读取 PROVIDER，也仍能理解包含 "provider" 的 /connect 负载。方便时请迁移到新名称——旧名称已弃用，但尚未移除。

• 主要功能
• MCP 概览
• 开始使用
• 沙盒变体
• 最佳实践
• 参与贡献
• 资源

🚀 主要功能

• ⚡ 实时控制： 即时查看 Notebook 的实时变化。
• 🔁 智能执行： 借助单元格输出反馈，在运行单元格失败时自动调整。
• 🧠 感知上下文： 理解整个 Notebook 上下文，让交互更贴合需求。
• 📊 多模态支持： 支持多种输出类型，包括图像、图表和文本。
• 📚 支持多个 Notebook： 在多个 Notebook 之间无缝切换。
• 🎨 集成 JupyterLab： 增强 UI 集成，例如自动打开 Notebook。
• 🤝 兼容 MCP： 可与任何 MCP 客户端配合使用，例如 Claude Desktop、Cursor、Windsurf 等。
• 🔍 可观测性： 内置钩子系统并集成 OpenTelemetry，可跟踪工具调用和内核执行。

兼容任何 Jupyter 部署（本地、JupyterHub 等），也兼容由 Datalayer 托管的 Notebook；其中的代码沙盒配备 GPU，且即使断开连接，执行也会继续。

🔧 MCP 概览

🔧 工具概览

所有工具及其参数、架构和返回值，均根据运行中服务的实时快照生成，并发布在 jupyter-mcp-server.datalayer.tech/mcp 上——因此它始终与代码保持同步，而复制到此文件中的表格则无法做到这一点。

这些工具分为四组：

• 服务和代码沙盒 — 浏览 Jupyter 文件系统、列出内核、在运行时连接到服务，以及启动、选择和终止代码沙盒。
• Notebook — 打开、创建和切换 Notebook，列出 Notebook、读取 Notebook、重启其内核并释放 Notebook。
• 单元格 — 逐项或批量读取、插入、删除、移动、重新排序和编辑单元格，并清除单元格输出。
• 执行 — 在活动后端运行单元格或任意代码；在沙盒支持时，提供多模态输出和流式传输。

沙盒工具需要可选的 jupyter_mcp_sandboxes 扩展；请参阅 沙盒变体。

JupyterLab 集成

仅在启用 JupyterLab 模式时可用。默认情况下已启用。

在 JupyterLab 模式下，服务还会通过 jupyter-mcp-tools 将 JupyterLab 命令作为 MCP 工具提供——默认包括 notebook_run-all-cells 和 notebook_get-selected-cell，还可以通过 allowed_jupyter_mcp_tools 选择更多命令。完整列表和配置方法请参阅 Additional Tools 文档。

📝 提示词概览

该服务实现了 MCP 提示词功能。 jupyter-cite 可以引用 Notebook 中的特定单元格，类似于在编码 IDE 或 命令行中使用 @。输入参数和返回内容请参阅 Prompts 文档。

🏁 开始使用

如需完整的设置说明（包括 Streamable HTTP 传输、作为 Jupyter Server 扩展运行以及高级配置），请参阅我们的文档。或者，也可以在下方通过 JupyterLab 和 STDIO 传输快速开始。

1. 设置环境

pip install jupyterlab jupyter-collaboration jupyter-mcp-tools ipykernel

要确认环境配置正确：

1. 在 JupyterLab 中打开一个笔记本
2. 在任意单元格中输入一些内容（代码或 Markdown）
3. 查看标签页指示符：笔记本名称旁应出现“×”，表示有未保存的更改
4. 等待几秒钟，“×”应自动变为“●”，无需手动保存

自动保存行为表明实时协作功能正常运行，这是集成 MCP 服务的必要条件。

2. 启动 JupyterLab

# Start JupyterLab on port 8888, allowing access from any IP and setting a token
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

如果你通过 JupyterHub 而非上述 JupyterLab 运行笔记本，请参阅我们的 JupyterHub 设置指南。

3. 配置首选的 MCP 客户端

接下来，配置 MCP 客户端以连接到服务。我们提供两种主要方式，请选择最适合你需求的一种：

• 📦 使用 uvx（推荐用于快速开始）： 使用 uv 的轻量快速方式，适合本地开发和初次使用者。
• 🐳 使用 Docker（推荐用于生产环境）： 容器化方案，可确保环境一致且相互隔离，非常适合生产环境或复杂配置。

pip install uv
uv --version
# should be 0.6.14 or higher

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

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JUPYTER_URL",
        "-e", "JUPYTER_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://host.docker.internal:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JUPYTER_URL",
        "-e", "JUPYTER_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

1. 端口配置：确保 Jupyter URL 中的 port 与 jupyter lab 命令使用的端口一致。为简化配置，可在 JUPYTER_URL 中设置此项。
2. 服务分离：两个服务位于同一台服务器时使用 JUPYTER_URL；对于高级部署，可分别设置各变量。之所以提供不同的 URL 变量，是因为某些部署会将笔记本存储（DOCUMENT_URL）与内核执行（CODE_SANDBOX_URL）分开。
3. 身份验证：在大多数情况下，文档服务和代码沙箱服务使用相同的身份验证令牌。为简化配置，可使用 JUPYTER_TOKEN；如果凭据不同，则分别设置 DOCUMENT_TOKEN 和 CODE_SANDBOX_TOKEN。
4. 笔记本路径：DOCUMENT_ID 参数指定 MCP 客户端默认连接的笔记本路径。该路径应相对于启动 JupyterLab 的目录。如果省略 DOCUMENT_ID，MCP 客户端可以自动列出 Jupyter 服务上所有可用的笔记本，让你通过提示词交互式地选择一个笔记本。
5. 图像输出：如果你的 LLM 不支持多模态理解，请将 ALLOW_IMG_OUTPUT 设为 false。

有关配置各类 MCP 客户端的详细说明，包括 Claude Desktop、VS Code、Cursor、Cline 和 Windsurf，请参阅 MCP 客户端配置。

🧩 沙盒变体

默认情况下，代码通过 code-sandboxes 的 jupyter-server 变体在 Jupyter Server 上执行（SANDBOX_VARIANT=jupyter-server）。将 SANDBOX_VARIANT 设置为其他值时，如果所选变体提供了普通内核客户端，则会通过沙盒的普通内核客户端使用另一个 code-sandboxes 引擎，这样相同的笔记本工具就能在更多后端上运行代码。

变体名称的拼写不必严格一致：google_colab、google-colab 和 GOOGLE-COLAB 都表示同一个变体。下方列出的是规范名称。

沙盒功能由可选扩展 jupyter_mcp_sandboxes 提供。要使用沙盒生命周期工具（launch_sandbox、list_sandboxes、use_sandbox、terminate_sandbox）或运行任何非 jupyter-server 沙盒变体，请使用 pip install jupyter_mcp_sandboxes 安装该扩展。

每种引擎都有专属页面，介绍所需凭据、支持的加速器选项以及配置示例客户端——请从 jupyter-mcp-server.datalayer.tech/code-sandboxes 开始。

🧪 测试

运行测试套件：

pytest tests/

测试所需的环境变量：

• 默认本地测试套件无需设置。

可选环境变量：

• TEST_MCP_SERVER：用于切换独立 MCP 服务模式测试的 true/false 开关（默认值为 true）。
• TEST_JUPYTER_SERVER：用于切换 Jupyter 扩展模式测试的 true/false 开关（默认值为 true）。
• DATALAYER_API_KEY：仅 Datalayer 云端冒烟测试／集成测试需要。
• DATALAYER_RUN_URL：供 Datalayer 引擎测试使用的可选自定义 Datalayer 代码沙盒 URL。
• SANDBOX_ENVIRONMENT：可选的云环境覆盖值（例如 ai-agents-env）。

✅ 最佳实践

• 与支持多模态输入的大模型（如 Gemini 2.5 Pro）交互，以充分利用高级多模态理解能力。
• 使用支持返回图像数据并能解析图像数据的 MCP 客户端（如 Cursor、Gemini CLI 等），因为有些客户端可能不支持此功能。
• 将复杂任务（如完整的数据科学工作流）拆分为多个子任务（如数据清理、特征工程、模型训练、模型评估等），并逐步执行。
• 提供结构清晰的提示词和规则（👉 访问我们的 提示词模板 开始使用）
• 尽可能提供更多上下文（如已安装的软件包、现有数据集的字段说明、当前工作目录、详细的任务要求等）。

🤝 参与贡献

欢迎各种形式的贡献！以下是一些示例：

• 🐛 修复 Bug
• 📝 改进现有功能
• 🔧 开发新功能
• 📚 改进文档和提示词模板

关于如何开始开发并提交贡献的详细说明，请参阅我们的 贡献指南。

贡献者

📚 资源

想查找有关 Jupyter MCP Server 的博客文章、视频或其他资料？

👉 请访问文档中的 资源部分，了解更多！

如果这个项目对你有帮助，请给我们一个 ⭐️

由 Datalayer 倾心打造 ❤️