Jupyter MCP来了，让AI直接动手跑你的Jupyter Notebook

大家好，我是 Ai 学习的老章

做数据分析的朋友，应该都被同一件事折磨过

你让 AI 帮你写一段 pandas 代码，它写得挺好，你复制粘贴到 Jupyter 里跑，报错了，你再把报错贴回去，它改一版，你再粘贴回去跑……一来一回十几个回合，AI 全程像个隔着玻璃指挥的人，它看不到你的 kernel 里有哪些变量，读不到你工作区里那个 data.csv，更没法自己跑一行代码验证一下想法

说白了，AI 和你的 Notebook 之间，隔着一道叫「复制粘贴」的墙

今天要介绍的 Jupyter MCP Server，就是来拆这道墙的，它让 AI 能直接连进你正在跑的 Jupyter，自己读 cell、自己插代码、自己执行、自己看运行结果——连图表输出都能看懂，我研究了一圈，觉得这东西对重度用 Notebook 搞数据科学的人，是真有用

简介

Jupyter MCP Server 是 Datalayer：datalayer⋅io 团队开源的一个 MCP 服务器，一句话定位：让 AI 通过 MCP 协议实时连接和操作 Jupyter Notebook

它解决的核心痛点，前面那个复制粘贴的故事已经讲透了——传统 AI 辅助编程，模型只能靠聊天记录里的上下文干活，对你真实的运行环境一无所知，而 Jupyter MCP Server 把这层关系彻底打通，让 AI 成了能直接上手操作 Notebook 的「实习生」

一张图看清这两种方式的区别：

传统 AI 辅助 vs Jupyter MCP Server 对比

下面这张图是官方的多模态实时操作演示，可以看到 AI 在左侧对话，右侧 Notebook 里的 cell 实时被创建、执行，连画出来的图都能被模型理解：

核心功能与特点：

• 实时控制 ：Notebook 的变化即时可见，AI 插一个 cell、跑一段代码，你在界面上立刻看到，不是事后同步

• 智能纠错 ：cell 执行失败了，AI 能拿到报错输出，自动调整重跑——这就是把前面那个「复制粘贴报错」的循环，交给机器自己闭环了

• 上下文感知 ：理解整个 Notebook 的上下文，知道你前面定义了哪些变量、跑到哪一步了，给的建议才真正贴合你的现场

• 多模态支持 ：支持图像、图表、文本等多种输出类型，配合 Gemini 2.5 Pro 这类多模态模型，AI 能「看懂」你画的图，这点很关键

• 多 Notebook 切换 ：可以在多个 Notebook 之间无缝切换，复杂项目不用反复手动指定

• JupyterLab 深度集成 ：能自动打开 Notebook 等 UI 层操作，体验更顺

• 广泛兼容 ：任何 MCP 客户端都能用，Claude Desktop、Cursor、Windsurf、VS Code 都行

• 可观测性 ：内置 hook 系统，集成了 OpenTelemetry，能追踪工具调用和 kernel 执行——这个细节说明它不是个玩具，是奔着生产环境去的

兼容性方面也给力，本地 Jupyter、JupyterHub、Datalayer 托管 Notebook 都能跑，甚至还在做 Google Colab 的实验性支持

它到底能干什么

这部分我觉得最值得讲，因为光看「实时控制」这种词太抽象，我们看它具体提供了哪些工具（Tools），就明白 AI 被赋予了多大的权限

它的工具集分了好几类，我挑重点说

服务器管理类：list_files 列文件、list_kernels 列 kernel、connect_to_jupyter 动态连接一个 Jupyter 服务器（不用重启 MCP 服务器就能切换，这个设计挺贴心）

多 Notebook 管理类：use_notebook 连接/新建/切换 Notebook、list_notebooks 列出所有 Notebook、restart_notebook 重启 kernel、read_notebook 读取 cell 内容

cell 操作与执行类，这是核心中的核心：

• read_cell / insert_cell / delete_cell / move_cell ：读、插、删、移动 cell

• overwrite_cell_source ：覆写某个 cell 的源码

• edit_cell_source ：对 cell 做精准的查找替换，不用整段重写——这个「外科手术式」编辑很懂程序员

• execute_cell ：带超时执行 cell，支持图像等多模态输出

• insert_execute_code_cell ：插入一个 cell 并一步执行

• execute_code ：直接在 kernel 里跑代码，连 magic 命令和 shell 命令都支持

你看这套工具，基本上把一个人在 Jupyter 里能干的事——读代码、改代码、跑代码、看结果、管 kernel——全都给 AI 开放了，这才叫真正的「上手操作」

它还支持 MCP 的 Prompt 特性，有个 jupyter-cite 可以像 IDE 里 @ 那样引用特定 Notebook 的 cell

一个加分项：可视化 cell 索引

这里要单独提一个配套扩展 jupyter-mcp-tools：github⋅com/datalayer/jupyter-mcp-tools，它把 JupyterLab 的命令也暴露成了 MCP 工具，让 AI 能触发「运行全部 cell」「获取当前选中 cell」这类操作

它有个很实用的小设计：装上之后，每个 cell 左边会用橙色斜体显示一个索引编号

橙色斜体显示的 cell 索引

为什么要这个？因为 jupyter-mcp-server 的工具是靠索引来定位 cell 的，你跟 AI 说「把第 3 个 cell 改一下」，它就能精准找到，有了可见的编号，人机协作时双方对的是同一个坐标系，不容易鸡同鸭讲，细节见真章

安装

老章必须强调一句：下面所有命令都来自官方文档，别凭印象瞎敲

先把环境装起来，官方推荐的快速上手是 JupyterLab + STDIO 传输方式：

pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel pycrdt

这里有个 v1.0.2 的更新值得一提：现在 pycrdt 已经原生支持，不用再额外装 datalayer_pycrdt 了，省事

装完启动 JupyterLab，开个端口、设个 token：

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

官方有个很贴心的验证小技巧：打开一个 Notebook，在 cell 里随便敲点东西，观察标签页上的标记，应该先出现一个「×」表示未保存，等几秒会自动变成「●」，这说明实时协作功能正常工作了——而这正是 MCP 集成的前提

配置 MCP 客户端

官方给了两种方式，我都列出来

方式一：用 uvx（推荐快速上手）

先装 uv：

pip install uv
uv --version
# 需要 0.6.14 或更高版本

然后在你的 MCP 客户端里这样配：

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

方式二：用 Docker（推荐生产环境）

macOS 和 Windows 上注意 JUPYTER_URL 要用 host.docker.internal：

{
  "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 改回 localhost，并加上 --network=host 参数即可

这里有两个坑要提醒：

1. v1.0.0 是个 breaking change，必须在 MCP 客户端里配置 MCP_TOKEN ，老版本升上来的注意这点

2. 如果你用的 LLM 不支持多模态，记得把 ALLOW_IMG_OUTPUT 设成 false ，否则图像输出会给模型添乱

如果你只是单机自己用，STDIO 传输方式足够了，配置简单、不用额外开端口、适合 Claude Desktop 这类桌面应用，缺点是一次只能一个客户端连

但如果你要做 Web 应用、多人并发、生产部署，那就该上 Streamable HTTP 传输方式，它能多客户端同时连，还能直接作为 Jupyter Server 扩展运行，省掉单独跑一个 MCP 服务器进程的麻烦

作为 Jupyter Server 扩展安装也很简单：

pip install jupyter-mcp-server
jupyter server extension enable jupyter_mcp_server

然后用这个命令确认扩展启用成功：

jupyter server extension list

看到 jupyter_mcp_server 在已启用列表里就对了，扩展会在 /mcp/v1 路径暴露 API 端点

Provider 这块也给得很全：本地/远程 Jupyter、JupyterHub 多用户部署、Datalayer 企业级托管、以及实验性的 Google Colab，基本覆盖了从个人到企业的各种场景

最佳实践

官方给了几条使用建议，我觉得挺实在，照搬给大家：

• 优先用支持多模态输入的模型（比如 Gemini 2.5 Pro），才能把图表理解能力吃满

• 选一个能返回并解析图像数据的 MCP 客户端（比如 Cursor、Gemini CLI），有些客户端不支持这个特性

• 把复杂任务拆开，别想着一句话让 AI 把整个数据科学流程跑完，拆成数据清洗、特征工程、模型训练、模型评估几步，一步步来

• prompt 写清楚，把已装的包、数据集字段含义、当前工作目录、详细任务要求都喂给它，上下文给得越足，AI 干得越准

先说好的地方：这个项目的工具设计是真用心，edit_cell_source 的外科手术式编辑、靠索引定位 cell、内置 OpenTelemetry 可观测性，这些细节都说明团队是认真在做生产级产品，不是赶时髦做个 demo，对于天天泡在 Jupyter 里做数据分析、模型实验的人，它能实实在在把「人肉搬运代码」的活儿省掉

再说要注意的坑：

• 安全性这块得拎清楚，你等于是给外部 AI 应用开放了执行代码、读写文件、操作 kernel 的权限，token 一定管好，别在公网裸奔，官方文档专门有 security 章节，建议认真读一遍

• 多模态能力强依赖客户端和模型，如果你的模型或客户端不支持图像，体验会打折

• JupyterHub 和 Google Colab 的支持还在完善中，官方也在公开征集这两块的反馈，生产上用要谨慎

Jupyter MCP Server 的价值不在于多花哨，而在于把「AI 隔着玻璃指挥」这件最别扭的事给解决了，让 AI 从一个只会聊天的顾问，变成一个能直接上手跑代码、看结果、自己纠错的助手，工具集完整、部署方式灵活、还带可观测性，是个能放心往生产里用的方案