Jupyter MCP Server

对于数据科学家、研究人员和AI工程师来说，Jupyter Notebook 是探索数据、开发模型的核心环境。但当我们与 AI 助手协作时，一个断裂点始终存在：AI 可以看到代码，却无法直接执行、调试或观察结果。Jupyter MCP Server 的出现弥合了这一鸿沟。它将整个 Jupyter 环境的能力通过模型上下文协议（MCP）暴露给 AI，让大语言模型能够实时控制笔记本、执行代码、读取输出，甚至处理图像和图表，真正成为你在数据科学工作流中的“搭档”。

项目基本信息

一、项目介绍

Jupyter MCP Server 是一个专为 AI 开发设计的 MCP 服务器，它作为桥梁，将 Jupyter Notebook 与 MCP 客户端（如 Claude Desktop、Cursor、Windsurf 等）连接起来。它的目标很明确：让 AI 能够在 Jupyter 环境中执行代码、管理笔记本，并理解多模态输出。

核心能力概览

该服务器提供了一套极为丰富的工具集，可大致分为以下几类：

关键特性

• 实时控制：AI 执行代码后，输出会即时返回，你可以看到单元格的输出变更。
• 智能执行：当单元格运行失败时，服务器会返回错误信息，AI 可以据此自动调整代码并重试，形成一个反馈闭环。
• 上下文感知：AI 能够理解整个笔记本的上下文——包括之前的代码、数据和已加载的变量——从而实现更有意义的交互。
• 多模态支持：支持文本、图像、图表等多种输出类型。如果你的 LLM 支持多模态，它可以直接“看见”单元格输出的图表。
• 多笔记本支持：可以同时连接多个笔记本，并在它们之间无缝切换。

二、核心优势

真正的 AI 辅助数据科学

与只能“看”代码的 AI 不同，Jupyter MCP Server 赋予了 AI 执行能力。你可以用自然语言指挥 AI 完成数据清洗、特征工程、模型训练和评估的全流程，AI 不仅写代码，还会跑代码、看结果、改正错误。

深度 JupyterLab 集成

该服务器与 JupyterLab 紧密集成，提供了如自动打开笔记本、运行所有单元格等 UI 相关工具。这让你在 JupyterLab 中的手动操作和 AI 的自动操作可以协同进行。

多模态理解能力

如果你的 LLM（如 Gemini 2.5 Pro）支持多模态，它可以直接解析 execute_cell 返回的图像输出，这意味着 AI 能“看懂”你生成的图表是否正确，并根据视觉反馈进行调整。

高度可配置与可扩展

通过 allowed_jupyter_mcp_tools 配置参数，用户可以自定义启用哪些工具。对于 JupyterHub 和 Google Colab 的支持也正在积极开发中，适用场景将进一步扩展。

三、适用场景

AI 驱动的数据探索

用户：加载 sales.csv 文件，查看前 10 行数据，然后对 revenue 列做一个按 region 分组的柱状图。

AI 会自动创建代码单元格、执行 pandas 读取和绘图命令，并将生成的图表作为输出返回。

自动化机器学习工作流

用户：使用 scikit-learn 对 iris 数据集进行 KNN 分类，评估准确率，并画出混淆矩阵。

AI 会依次完成数据加载、模型训练、评估和可视化，并在代码出错时根据错误信息自行修正。

教学与演示辅助

教师或技术分享者可以让 AI 实时执行代码并展示结果，避免手动编码的拼写错误，让演示更专注在概念讲解上。

代码调试与修复

用户：第三个单元格报错了，帮我看看是什么问题并修复。

AI 会读取错误单元格的源代码和输出来诊断问题，然后覆盖修复并重新执行。

四、安装教程

环境要求

第一步：设置 JupyterLab 环境

# 安装所需包
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

验证环境：在 JupyterLab 中打开一个笔记本，输入任意内容。等待几秒钟，笔记本名称旁的 x 应自动变为 ●，这表示实时协作功能正常工作。

第二步：启动 JupyterLab

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

在这里，MY_TOKEN 是你设置的访问令牌，请替换为自己的密钥。

第三步：配置 MCP 客户端

推荐方式：使用 uvx（快速开始）

编辑你的 MCP 客户端配置文件（以 Claude Desktop 为例）：

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

Docker 方式（生产环境推荐）

{
  "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://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

Linux 系统需额外添加 "--network=host" 参数。

保存配置文件后，完全退出并重启 MCP 客户端。

五、使用示例

示例一：基本数据探索

用户：加载 iris.csv 数据集，打印前 5 行，然后显示数据的基本统计信息。

AI 调用 insert_execute_code_cell，自动插入并执行如下代码：

import pandas as pd
df = pd.read_csv('iris.csv')
print(df.head())
print(df.describe())

示例二：可视化与多模态输出

用户：用 matplotlib 画出 sepal_length 和 sepal_width 的散点图，按 species 着色。

AI 插入并执行绘图代码。如果你的 LLM 支持多模态，它能直接返回并“描述”生成的图表。否则，你可以通过资源接口获取图像文件。

示例三：跨单元格上下文操作

用户：在笔记本最后添加一个 Markdown 单元格，总结上面所有分析的主要发现。

AI 先调用 read_notebook 读取全部单元格内容，理解分析结果，然后调用 insert_cell 插入一个 Markdown 单元格，内容为它基于上下文生成的总结。

示例四：错误自动修复

用户：第二个单元格运行报错了，帮我看看是什么问题并修复它。

AI 调用 read_cell 查看出错单元格的源代码和错误输出，分析原因，然后调用 overwrite_cell_source 修复代码，最后调用 execute_cell 重新运行。

六、常见问题

问：配置后 AI 提示“无法连接到 Jupyter 服务器”怎么办？

答：请检查：

1. JupyterLab 是否正在运行，且端口与 JUPYTER_URL 一致。
2. 令牌 (JUPYTER_TOKEN) 是否与启动 JupyterLab 时设置的 MY_TOKEN 匹配。
3. 如果是 Docker 方式运行，确保网络配置正确（Windows/macOS 使用 host.docker.internal，Linux 使用 --network=host）。

问：我的 LLM 不支持多模态，图像输出会怎样？

答：即使 LLM 不支持多模态，服务器仍能处理图像输出。你可以设置 ALLOW_IMG_OUTPUT: "true"，AI 会以资源链接的形式返回图像，你可以在 MCP 客户端中查看。如果设为 "false"，图像输出将被忽略。

问：如何同时操作多个笔记本？

答：使用 use_notebook 工具切换当前连接的笔记本。你可以先用 list_notebooks 查看所有可用笔记本，然后指定路径进行连接。不同笔记本之间的内核和变量是独立的。

问：这个工具支持 Google Colab 吗？

答：根据项目公告，对 Google Colab 和 JupyterHub 的支持正在积极开发中。目前已完全支持本地 JupyterLab 部署和 Datalayer 托管的 Notebook。

七、总结

Jupyter MCP Server 是数据科学工作流与 AI 辅助开发深度融合的一次重要突破。它将 Jupyter 从“需要人工操作”的笔记本环境，升级为“AI 可以直接参与”的协作平台。通过丰富的工具集、实时反馈闭环和多模态支持，它让 AI 不仅仅是代码的生成者，更成为代码的执行者、结果的观察者和错误的修正者。

对于数据科学家、机器学习工程师和教育工作者来说，花十几分钟完成配置，你将获得一位能够真正“上手干活”的 AI 搭档。