Jupyter Notebook MCP Server (for Cursor)

基本能力

产品定位

cursor-notebook-mcp 是一个专为在 Cursor 中与 Jupyter Notebook 文件交互而设计的 MCP 服务器，提供了一套工具来直接操作笔记本单元格。

核心功能

• 创建、删除、重命名笔记本文件
• 读取笔记本结构和单元格内容
• 添加、编辑、删除、移动、拆分、合并单元格
• 读取和编辑笔记本及单元格的元数据
• 清除单元格输出
• 验证笔记本结构
• 导出笔记本到其他格式（如 Python、HTML）

适用场景

• 在 Cursor 中直接编辑 Jupyter Notebook 文件
• 自动化笔记本单元格操作
• 批量处理笔记本文件
• 笔记本文件的格式转换

工具列表

• notebook_create: 创建新的空笔记本文件
• notebook_delete: 删除现有笔记本文件
• notebook_rename: 重命名/移动笔记本文件
• notebook_read: 读取整个笔记本结构
• notebook_read_cell: 读取特定单元格的源内容
• notebook_add_cell: 在指定索引后添加新单元格
• notebook_edit_cell: 替换特定单元格的源内容
• notebook_delete_cell: 删除特定单元格
• notebook_change_cell_type: 更改单元格类型
• notebook_duplicate_cell: 复制单元格
• notebook_get_cell_count: 返回单元格总数
• notebook_read_metadata: 读取顶层笔记本元数据
• notebook_edit_metadata: 更新顶层笔记本元数据
• notebook_read_cell_metadata: 读取特定单元格的元数据
• notebook_read_cell_output: 读取特定代码单元格的输出列表
• notebook_edit_cell_metadata: 更新特定单元格的元数据
• notebook_clear_cell_outputs: 清除特定单元格的输出和执行计数
• notebook_clear_all_outputs: 清除所有代码单元格的输出和执行计数
• notebook_move_cell: 将单元格移动到不同位置
• notebook_split_cell: 在指定行号处拆分单元格
• notebook_merge_cells: 合并单元格与紧随其后的单元格
• notebook_validate: 验证笔记本结构
• notebook_get_info: 检索一般信息
• notebook_export: 将笔记本导出为其他格式

常见问题解答

• UI 刷新问题: 某些笔记本操作可能成功，但 Cursor UI 可能无法正确显示更新内容。可以关闭并重新打开笔记本文件，或保存文件以重新加载实际文件内容。
• 单元格执行限制: 该服务器无法执行笔记本单元格，仅操作 .ipynb 文件结构。

使用教程

使用依赖

Python 依赖

• Python 版本: 3.9+
• 核心: mcp>=0.1.0, nbformat>=5.0, nbconvert>=6.0, ipython, jupyter_core
• 可选 - SSE 传输: uvicorn>=0.20.0, starlette>=0.25.0
• 可选 - 开发/测试: pytest>=7.0, pytest-asyncio>=0.18, pytest-cov, coveralls

外部系统依赖

• Pandoc: 用于许多非 HTML 导出格式
• LaTeX (XeLaTeX 推荐): 用于将笔记本直接导出为 PDF

安装教程

从 PyPI 安装

# 基本安装（仅 stdio 传输）
pip install cursor-notebook-mcp

# 带 SSE 传输支持
pip install "cursor-notebook-mcp[sse]"

开发安装（从源代码）

1. 克隆仓库:

git clone https://github.com/jbeno/cursor-notebook-mcp.git
cd cursor-notebook-mcp

1. 创建并激活虚拟环境:

python -m venv .venv
source .venv/bin/activate  # Windows 使用 `.venv\Scripts\activate`

1. 安装可编辑模式:

# 包括 SSE 和测试依赖
pip install -e ".[dev]"

调试方式

直接执行（推荐用于测试/开发）

# stdio 传输（默认）
python notebook_mcp_server.py --allow-root /path/to/notebooks

# sse 传输
python notebook_mcp_server.py --transport sse --allow-root /path/to/notebooks --host 127.0.0.1 --port 8080

使用安装的脚本

# stdio 传输
cursor-notebook-mcp --allow-root /path/to/notebooks

# sse 传输
cursor-notebook-mcp --transport sse --allow-root /path/to/notebooks --host 127.0.0.1 --port 8080

许可证

该项目遵循 MIT 开源许可条款，请参阅 MIT 了解完整条款。