jupyter-mcp-server

图1：Jupyter MCP Server 多模态 Notebook 操作演示

---

想象一下这样的场景：你在开发一个大模型项目，代码散落在多个 Jupyter Notebook 里，每次测试都要手动切换标签页、复制粘贴结果，效率低下。更头疼的是，当 AI 助手需要理解你的代码逻辑时，它只能看到冷冰冰的文本——无法感知 Notebook 的运行状态、单元格输出、甚至内核是否还活着。

Jupyter MCP Server 正是为解决这个痛点而生。它将 Jupyter Notebook 的核心能力以 MCP（Model Context Protocol） 接口暴露出来，让 AI 助手能够实时感知、操作、甚至协同编辑正在运行的 Notebook 环境。

---

背景：从"哑终端"到"智能协作"的技术跃迁

Jupyter Notebook 是数据科学和 AI 领域无可争议的事实标准。然而，传统 Jupyter 采用的是请求-响应模式——用户主动操作，内核被动执行，AI 助手无法主动感知 Notebook 的状态变化。

Datalayer 团队敏锐地捕捉到了这个协作瓶颈。作为一家专注于 Jupyter 生态的公司，Datalayer 此前已有 jupyter-server、jupyterlab 等多个深度参与项目，积累了对 Jupyter 内核通信协议的深刻理解。在此基础上，团队于 2024 年初启动了 Jupyter MCP Server 项目，目标是将 Jupyter 的实时交互能力通过 MCP 协议开放给所有 AI 客户端。

[!NOTE] 项目当前正在积极开发 JupyterHub 和 Google Colab 集成，计划支持企业级部署场景。

---

核心能力：14 工具覆盖 Notebook 全生命周期

Jupyter MCP Server 将功能封装为 14 个 MCP 工具，分为三大类别：

服务器管理层（2 个）

• Connect Jupyter — 与远程 Jupyter 服务器建立连接，支持 token 认证
• List Kernels — 列出当前活跃的内核，支持查看各内核的执行状态

这一层解决的是"AI 如何找到并接入正确的 Jupyter 环境"的问题。项目支持两种连接模式：

• JUPYTER_SERVER 模式（扩展模式）：以 Jupyter Server 扩展形式运行，直接调用 Jupyter 内核 API，延迟最低
• MCP_SERVER 模式（独立模式）：通过 HTTP/WebSocket 连接远程 Jupyter 服务器，适合容器化部署场景

多 Notebook 管理（5 个）

• List Notebooks — 列出所有可用 Notebook
• Use Notebook — 切换当前操作的 Notebook 上下文
• Unuse Notebook — 退出当前 Notebook 操作上下文
• Read Notebook — 读取指定 Notebook 的完整结构（单元格、输出、markdown）
• Restart Notebook — 重启内核（用于清除状态）

这些工具使 AI 能够在多 Notebook 场景下自如切换。比如一个数据管道项目可能包含 data-loading.ipynb、feature-engineering.ipynb、training.ipynb 三个文件，AI 可以按需读写每个文件，而无需用户手动切换。

单元格操作（7 个）

• Insert Cell — 在指定位置插入新单元格
• Edit Cell Source — 编辑现有单元格的代码/文本
• Overwrite Cell Source — 覆盖指定单元格的源代码
• Delete Cell — 删除指定单元格
• Move Cell — 调整单元格的顺序
• Read Cell — 读取单个单元格的源代码和输出
• Execute Cell — 执行指定单元格（含输出捕获）

配合 Execute Code 工具（直接执行 Python/Shell 代码），AI 可以对 Notebook 进行完整的增删改查操作，实现"AI 编写代码 → AI 执行验证 → AI 读取结果"的自动化闭环。

[!IMPORTANT] v1.0.0 重大变更：从 v1.0.0 起，必须在 MCP 客户端配置中设置 MCP_TOKEN，否则无法连接。

---

技术架构：双模式驱动的精妙分层

从 ARCHITECTURE.md 可以清晰看到项目的分层架构：

┌─────────────────────────────────────┐
│   MCP Client (Claude/Cursor/VSCode) │
└──────────┬──────────────────────────┘
           │ stdio / SSE / HTTP
    ┌──────▼──────┐   ┌──────────────┐
    │ MCP_SERVER   │   │JUPYTER_SERVER│
    │ Standalone   │   │ Extension    │
    └──────┬──────┘   └──────┬───────┘
           │                 │
    ┌──────▼─────────────────▼───────┐
    │     Tool Implementation Layer  │
    │  (jupyter_mcp_server/tools/)   │
    └─────────────────────────────────┘

核心依赖栈：

层级	技术选型	说明
MCP 协议层	mcp[cli] >= 1.10.1	官方 Python SDK，处理协议序列化
HTTP 服务层	fastapi + uvicorn + starlette	提供 streamable-http 传输
认证层	Bearer Token（MCP_TOKEN）	v1.0.0 引入，替代明文传输
Jupyter 通信	jupyter-kernel-client	管理内核生命周期
Notebook 建模	pydantic	严格的类型定义（Cell、Notebook 等）
数据格式	jupyter-nbmodel-client	解析和操作 .ipynb 文件
可观测性	opentelemetry-api/sdk	分布式追踪支持

值得注意的是，项目对测试覆盖极为重视：CI 中同时运行 TEST_MCP_SERVER=true 和 TEST_JUPYTER_SERVER=true 两套测试套件，确保两种运行模式行为一致。

---

上手体验：安装即用的门槛有多高？

安装方式

项目提供两种安装途径：

方式一：pip 安装（推荐个人用户）

pip install jupyter-mcp-server

方式二：Docker 部署（推荐服务器场景）

docker pull datalayer/jupyter-mcp-server:latest
docker run -i --rm \
  -e JUPYTER_URL=http://localhost:8888 \
  -e JUPYTER_TOKEN=*** \
  -e START_NEW_RUNTIME=true \
  --network=host \
  datalayer/jupyter-mcp-server:latest

启动配置

以 streamable-http 模式启动（与 Claude Desktop、Cursor 等 MCP 客户端配合）：

jupyter-mcp-server start \
  --transport streamable-http \
  --jupyter-url http://localhost:8888 \
  --jupyter-token MY_TOKEN \
  --start-new-runtime true \
  --port 4040

⚠️ 必须设置 --mcp-token（或环境变量 MCP_TOKEN），否则 MCP 客户端无法认证连接。

硬件需求

这是一个纯 CPU 运行的项目，不需要 GPU。依赖解析和内核通信本身不涉及张量运算，资源占用极低（实测 512MB RAM 即可流畅运行）。

---

局限性：光环之下的现实约束

尽管功能强大，项目仍有几个需要正视的局限：

1. 无 Web 界面：这是一个纯 CLI 工具，没有图形化控制台。对于不熟悉命令行的用户，上手门槛相对较高。

2. 依赖外部 Jupyter：MCP Server 本身不包含 Jupyter，需要连接到已有的 Jupyter Server 或启动一个。对于完全不了解 Jupyter 的用户，需要额外学习成本。

3. v1.0.0 Breaking Change：从 1.0.0 起引入 MCP_TOKEN 认证，如果从旧版本升级需要重新配置 MCP 客户端。

4. 多用户场景未成熟：当前版本对 JupyterHub（多用户 Jupyter 平台）的支持正在开发中，企业场景直接使用有一定风险。

5. 品牌强依赖 Datalayer 生态：项目大量依赖 Datalayer 维护的内部库（如 jupyter-nbmodel-client、jupyter-server-nbmodel），一旦 Datalayer 停止维护，可能面临依赖断裂风险。

---

行业意义：AI 编程工具链的关键拼图

Jupyter MCP Server 的出现填补了 AI 助手与 Jupyter 生态之间的最后一公里。

当前主流 AI 编程工具（如 Claude Code、Cursor）已经具备出色的代码生成能力，但它们对交互式数据分析环境的感知仍然有限——无法看到某个 Cell 的输出、无法知道内核是否崩溃、无法读取用户之前的探索性分析。Jupyter MCP Server 通过标准化的 MCP 协议将这一切透明化。

从更大的视角看，随着 Claude Desktop、VS Code Cursor 插件等 MCP 客户端的普及，Jupyter MCP Server 正在成为 AI + 数据科学工作流的标准中间件，其价值类似于当年的 Jupyter Kernel Gateway 在容器化时代的角色。

增长态势：项目 Star 数已达 1156，Fork 165，在 MCP Server 类项目中处于头部位置。随着 MCP 协议本身的生态扩张，该项目的影响力有望持续扩大。