jupyter-mcp-server MCP — 使用场景, 安装 & 实时演示

为什么要用

核心特性

实时控制运行中的 Jupyter kernel
多模态输出——捕获 matplotlib/plotly 图像回传给 Claude
单个会话内多笔记本切换
内置 OpenTelemetry 可观测性

实时演示

实际使用效果

jupyter.replay ▶ 就绪

0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "jupyter",
      "command": "uvx",
      "args": [
        "jupyter-mcp-server"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "jupyter": {
      "command": {
        "path": "uvx",
        "args": [
          "jupyter-mcp-server"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add jupyter -- uvx jupyter-mcp-server

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： jupyter-mcp-server

如何用 Claude + Jupyter 进行探索性数据分析

👤 数据科学家、分析师 ⏱ ~30 min intermediate

何时使用： 你有一个新数据集，想快速探索它而不用自己写模板代码。

前置条件

运行配置了 token 认证的 JupyterLab — jupyter lab --no-browser；从 URL 复制 token
JUPYTER_URL + JUPYTER_TOKEN 环境变量 — 设置为你的 lab URL 和 token

步骤

加载笔记本和数据

使用 use_notebook 打开 analysis.ipynb。插入一个单元格，将 ./data/events.parquet 加载到名为 df 的 DataFrame。✓ 已复制

→ 单元格执行；返回 df.head() 预览
迭代分析

event_type 的分布是什么样的？绘制它，给我看图像。✓ 已复制

→ 直方图图像在聊天中显示
保存整理好的笔记本

整理笔记本：删除出错的单元格，添加 markdown 标题，重启-全部运行来验证它从头到尾都能运行。✓ 已复制

→ 能够端到端重现的笔记本

结果： 一个可发布的笔记本，包含叙述、图表和验证的可重现性。

注意事项

Kernel 状态与笔记本单元格顺序不同步 — 编辑后使用 notebook_run-all-cells 来捕获隐藏状态的 bug
数据文件对 kernel 不可见 — Kernel 的当前工作目录是笔记本所在的目录，而不是你启动 Jupyter 的位置——使用绝对路径

搭配使用： filesystem

使用 Claude 和 jupyter-mcp 的自修复笔记本

👤 在管道上迭代的研究人员 ⏱ ~45 min advanced

何时使用： 一个长笔记本在中途失败；你想让 agent 修复单元格并继续，而不是重新启动。

步骤

运行并捕获错误

执行 pipeline.ipynb 中的所有单元格。当单元格出错时，读取回溯，修复代码，然后在继续之前重试。✓ 已复制

→ 笔记本越过第一个错误并应用了修复后继续
记录修复以供审查

将你所做的每个修复总结为已修改代码上方的 markdown 单元格✓ 已复制

→ agent 编辑的审计跟踪

结果： 管道完成，并有可见的修复历史。

从自然语言课程大纲生成教学笔记本

👤 教育工作者、技术写手 ⏱ ~30 min beginner

何时使用： 你想为学生或博客文章制作一个详细示例笔记本。

步骤

大纲→框架

从这个课程大纲[粘贴]，创建 lesson.ipynb，用 markdown 单元格作为部分，代码单元格框架化。✓ 已复制

→ 有结构的笔记本
填充代码单元格并验证

用可运行的示例充实每个代码单元格。从头到尾执行并确保零错误。✓ 已复制

→ 学生可以运行的干净笔记本

结果： 在几分钟而不是几小时内创建的教学就绪笔记本。

组合

与其他 MCP 搭配，撬动十倍杠杆

jupyter + filesystem

将工件移入或移出笔记本的工作目录

通过 filesystem MCP 将笔记本保存的图表复制到 ./reports/<date>/。✓ 已复制

jupyter + postgres

在笔记本内从 Postgres 拉取数据

在新单元格中，使用 pandas.read_sql 和我的数据库连接加载上个月的事件；然后进行数据探索。✓ 已复制

工具

此 MCP 暴露的能力

工具	输入参数	何时调用	成本
use_notebook	path: str	打开/附加笔记本	0
list_notebooks		查找可用笔记本	0
execute_cell	notebook_id, cell_index	运行特定单元格	kernel time
insert_execute_code_cell	notebook_id, code, position?	添加新代码并运行	kernel time
read_cell	notebook_id, cell_index	检查现有单元格	0
list_kernels		查看正在运行的内容；查找僵尸 kernel	0
restart_notebook	notebook_id	干净地重置 kernel 状态	0

成本与限制

运行它的成本

API 配额: MCP 无配额；Jupyter 由你自己运行
每次调用 Token 数: 输出可能很大——特别是图像和 DataFrame 头部
费用: 免费（自托管）
提示: 使用 df.head() 和 df.info() 而不是 print(df) ——完整的 DataFrame 会增加 token 使用量

安全

权限、密钥、影响范围

凭据存储： JUPYTER_TOKEN 在环境中——把它当作密码；拥有它的任何人都可以在你的 kernel 上运行代码

数据出站： MCP 仅与你的 Jupyter server URL 通信

故障排查

常见错误与修复

连接到 Jupyter 时 401 未授权

JUPYTER_TOKEN 过期——从 jupyter server list 复制新的

验证： curl -H 'Authorization: token <TOKEN>' $JUPYTER_URL/api

Kernel 繁忙 / 从不返回

上一个单元格仍在运行。使用 restart_notebook 恢复；注意无限循环

验证： list_kernels 显示 state=busy

图表不在 Claude 中显示

确保设置了 %matplotlib inline 并且你返回了图形，而不仅仅是在末尾调用 plt.show()

替代方案

jupyter-mcp-server 对比其他方案

替代方案	何时用它替代	权衡
nteract/papermill	你想要脚本化/参数化笔记本运行，不需要交互式聊天	没有 agent 循环；批处理风格
marimo	你想要反应式笔记本，减少隐藏状态	完全不同的工具；还没有 MCP

jupyter-mcp-server