[!IMPORTANT] v1.0.0 中的重大变更： 您必须在 MCP 客户端设置中配置 MCP_TOKEN。

有关设置详情，请参阅：https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-standalone/#3-configure-your-mcp-client

[!NOTE] 我们需要您的反馈！

我们正在积极开发对 JupyterHub 和 Google Colab 部署的支持。如果您正在使用或计划使用 Jupyter MCP 服务器与这些平台配合，我们非常期待听到您的意见！

• 🏢 JupyterHub 用户：请分享您的部署设置和需求
• 🌐 Google Colab 用户：请帮助我们了解您的使用场景和工作流程

欢迎加入我们的 社区页面，您的反馈将帮助我们确定功能优先级，并确保这些集成能够无缝满足您的需求。

📖 目录

• 关键特性
• MCP 概述
• 快速入门
• 最佳实践
• 贡献
• 资源

🚀 关键特性

• ⚡ 实时控制： 即时查看笔记本中的更改。
• 🔁 智能执行： 根据单元格输出反馈，自动调整失败的单元格运行。
• 🧠 上下文感知： 理解整个笔记本的上下文，以实现更相关的交互。
• 📊 多模态支持： 支持多种输出类型，包括图像、图表和文本。
• 📚 多笔记本支持： 轻松切换多个笔记本。
• 🎨 JupyterLab 集成： 增强的 UI 集成，例如自动打开笔记本。
• 🤝 MCP 兼容： 可与任何 MCP 客户端配合使用，例如 Claude Desktop、Cursor、Windsurf 等。
• 🔍 可观测性： 内置钩子系统，集成 OpenTelemetry，用于跟踪工具调用和内核执行。

兼容任何 Jupyter 部署（本地、JupyterHub 等）以及由 Datalayer 托管的笔记本。

🔧 MCP 概述

🔧 工具概述

该服务器提供了一组丰富的工具，用于与 Jupyter 笔记本进行交互，分类如下。有关每个工具的详细信息、参数和返回值，请参阅 官方工具文档。

服务器管理工具

多笔记本管理工具

单元格操作与执行工具

JupyterLab 集成

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

当以 JupyterLab 模式运行时，Jupyter MCP 服务器会与 jupyter-mcp-tools 集成，将额外的 JupyterLab 命令暴露为 MCP 工具。默认启用以下工具：

# 示例：通过命令行启用附加工具
jupyter lab --port 4040 --IdentityProvider.token MY_TOKEN --JupyterMCPServerExtensionApp.allowed_jupyter_mcp_tools="notebook_run-all-cells,notebook_get-selected-cell,notebook_append-execute,console_create"

📝 提示词概述

该服务器还支持 MCP 的 提示词功能，为用户提供一种与 Jupyter 笔记本交互的便捷方式。

有关每个提示词的详细信息、输入参数和返回内容，请参阅 官方提示词文档。

🏁 开始使用

如需全面的设置说明，包括 Streamable HTTP 传输、作为 Jupyter 服务器扩展运行以及高级配置，请查看 我们的文档。或者，您也可以通过下方的 JupyterLab 和 STDIO 传输快速开始。

1. 设置您的环境

pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17

[!TIP] 若要确认您的环境是否正确配置：

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

这种自动保存行为表明实时协作功能正常工作，这对于 MCP 服务器集成至关重要。

2. 启动 JupyterLab

# 在端口 8888 上启动 JupyterLab，允许从任何 IP 访问并设置令牌
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

[!NOTE] 如果您是通过 JupyterHub 而不是上述 JupyterLab 来运行笔记本，请参阅我们的 JupyterHub 设置指南。

3. 配置您首选的 MCP 客户端

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

• 📦 使用 uvx（推荐用于快速入门）： 一种轻量级且快速的方法，使用 uv 工具。非常适合本地开发和首次使用的用户。
• 🐳 使用 Docker（推荐用于生产环境）： 一种容器化方案，可确保一致且隔离的环境，非常适合生产环境或复杂部署。

pip install uv
uv --version
# 应该是 0.6.14 或更高版本

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

[!TIP]

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

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

✅ 最佳实践

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

🤝 贡献

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

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

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

我们的贡献者

📚 资源

正在寻找关于 Jupyter MCP Server 的博客文章、视频或其他资料吗？

👉 请访问我们文档中的 资源板块，获取更多信息！

托管部署

托管部署已在 Fronteir AI 上提供。

Jupyter MCP Server 快速上手指南

Jupyter MCP Server 是一个基于模型上下文协议（MCP）的服务器，旨在让 AI 助手实时连接、管理和操作 Jupyter Notebook。它支持代码执行、多模态输出（图片/图表）、多笔记本切换以及与 JupyterLab 的深度集成。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux, macOS 或 Windows (需安装 Docker 或 Python 环境)
• Python 版本: 推荐 Python 3.9+
• 前置工具:
  • pip (Python 包管理器)
  • uv (推荐的快速包管理工具，用于运行 MCP 服务)
  • Docker (可选，生产环境推荐)
• Jupyter 环境: 需要运行中的 JupyterLab 实例。

注意：本指南使用 uv 作为 MCP 客户端启动器，因为它更轻量且启动速度快。如果您尚未安装 uv，请先执行 pip install uv。

2. 安装与配置步骤

第一步：配置 Python 环境

安装必要的 Jupyter 组件及依赖。重要：必须安装特定版本的 datalayer_pycrdt 以确保实时协作功能正常，这是 MCP 服务器工作的基础。

# 安装核心依赖
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel

# 替换默认的 pycrdt 为 datalayer 优化版本
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17

验证环境： 启动 JupyterLab 后打开任意笔记本，输入内容并观察标签页指示器。如果看到 × 自动变为 ●（无需手动保存），说明实时协作功能已就绪。

第二步：启动 JupyterLab

启动 JupyterLab 服务，并设置访问令牌（Token）。请记下您设置的 MY_TOKEN 和端口号（默认为 8888）。

jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

• --IdentityProvider.token: 替换为您自定义的安全令牌。
• --ip 0.0.0.0: 允许外部连接（本地开发可设为 127.0.0.1）。

第三步：配置 MCP 客户端

根据您的 AI 编辑器（如 Cursor, Claude Desktop, Windsurf 等）配置文件格式，添加以下配置。

方案 A：使用 uvx (推荐，快速启动)

适用于本地开发。将以下 JSON 配置添加到您的 MCP 客户端配置文件中：

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

方案 B：使用 Docker (生产环境推荐)

适用于需要环境隔离的场景。

macOS / Windows:

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

Linux: 请将 JUPYTER_URL 中的 host 改为宿主机 IP（例如 http://172.17.0.1:8888）。

⚠️ 重要提示 (v1.0.0+)： 从 v1.0.0 版本起，必须在 MCP 客户端配置中正确设置 JUPYTER_TOKEN 环境变量，否则连接将失败。

3. 基本使用

配置完成后，重启您的 AI 编辑器或 MCP 客户端。现在您可以直接在对话中使用自然语言控制 Jupyter Notebook。

核心功能示例

• 创建并运行代码：

  "在当前笔记本中创建一个新单元格，计算 1 到 100 的和，并绘制结果的趋势图。" (AI 将自动调用 insert_execute_code_cell 和绘图库)

• 读取与分析：

  "读取当前笔记本的所有代码单元格，分析其中的数据清洗逻辑。" (AI 将调用 read_notebook 获取上下文)

• 多模态交互：

  "运行这个单元格并把生成的图表显示给我看。" (得益于 ALLOW_IMG_OUTPUT=true，AI 可以直接接收并展示图片输出)

• 引用特定内容：

  "@jupyter-cite 查看第 3 个单元格的输出结果。" (使用内置 Prompt 功能精准定位)

可用工具概览

AI 将自动调用以下工具与您交互：

• 文件管理: list_files, list_kernels
• 笔记本控制: use_notebook, restart_notebook, read_notebook
• 单元格操作: execute_cell, insert_cell, overwrite_cell_source
• JupyterLab 集成: notebook_run-all-cells (一键运行所有单元格)

现在，您已经成功搭建了 Jupyter MCP Server，可以开始体验 AI 驱动的实时数据分析工作流了。