Jupyter Notebook MCP Server (for Cursor)

Name: Jupyter Notebook MCP Server (for Cursor)
Author: jbeno

本地服务

github.com记忆与知识16151 周前更新

代码仓库访问官网

关于 Jupyter Notebook MCP Server (for Cursor)

Jupyter Notebook MCP Server 是一个 MCP 服务，允许 Cursor 中的 AI Agent 直接读取和编辑 .ipynb 文件的单元格。它基于 nbformat 操作笔记本结构，并将操作限制在用户指定的目录内。该项目并非 Cursor 专用，也可配置于 VS Code 或 Claude Code 等支持 MCP 的环境。

主要功能

01读取、添加、编辑、删除和移动单元格
02搜索单元格并生成笔记本大纲
03清除输出并编辑单元格输出
04通过 nbconvert 导出为 Python、HTML 等格式
05支持 stdio、Streamable HTTP 与 SSE 传输

适用场景

01让 Cursor 中的 Agent 按对话要求修改笔记本单元格
02在远程 SSH 服务器上通过 SFTP 编辑笔记本
03将笔记本导出为 Python 脚本或 HTML 文档

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 notebook_read、notebook_edit_cell、notebook_export 等约 26 个笔记本操作工具。

#jupyter #mcp #jupyter-notebook #ipynb #cursor #mcp-server #mcp-tools

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Jupyter Notebook MCP 服务（适用于 Cursor）

此目录包含一个 Model Context Protocol（MCP）服务，旨在让 Cursor 中的 AI Agent 能够与 Jupyter Notebook（.ipynb）文件交互。它的创建是为了解决 Cursor 的一项限制。截至版本 0.50.5，在 Agent 模式下，模型无法根据 AI 聊天面板中的对话编辑笔记本或笔记本单元格。此服务为 Agent 提供了一套 MCP 工具，可直接操作笔记本单元格。

虽然此 MCP 服务旨在解决 Cursor 的一项限制，但除了配置说明外，它没有任何专门针对 Cursor 的内容。你可以轻松配置它，以便与 VS Code（Insiders）、Claude Code，或任何能够利用 MCP 的模型/Agent 配合使用。请注意，VS Code（Insiders）现在对 Jupyter Notebook 的支持相当完善。

此 MCP 服务使用 nbformat 库安全地操作笔记本结构，并通过将操作限制在用户定义的目录中来实施安全保护。它还使用 nbconvert，以便将笔记本导出为 Python 脚本、HTML 等多种格式。服务通过简洁的 API 处理所有笔记本操作，以维护笔记本的完整性并避免产生格式错误的更改。

视频演示

Notebook MCP Server 0.3.0 更新（YouTube）

介绍 0.3.0 版本的更新和新工具
FastMCP 升级，支持 streamable HTTP 传输
支持通过 SFTP 编辑远程 SSH 服务上的 Jupyter Notebook，
解决问题（#2、#4、#5）并列出已知问题（#1、#3）

Notebook MCP Server 概览（YouTube）

直接在 Cursor 中编辑笔记本的当前限制。
安装和配置 Notebook MCP Server。
从头创建笔记本（示例：不到 2 分钟完成奇异值分解教程）。
演示各种编辑工具（编辑、拆分和复制单元格）。
读取笔记本元数据。
将笔记本导出为 python

功能

提供以下 MCP 工具（注册在 notebook_mcp 服务下）：

notebook_create：创建一个新的空笔记本文件。
notebook_delete：删除现有笔记本文件。
notebook_rename：将笔记本文件从一个路径重命名或移动到另一个路径。
notebook_read：读取整个笔记本，并以字典形式返回其结构。
notebook_read_cell：读取指定单元格的源内容。
notebook_add_cell：在指定索引之后添加新的代码或 Markdown 单元格。
notebook_edit_cell：替换指定单元格的源内容。
notebook_delete_cell：删除指定单元格。
notebook_change_cell_type：更改单元格类型（代码、Markdown 或原始文本）。
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：根据 nbformat 架构验证笔记本结构。
notebook_get_info：获取常规信息（单元格数量、元数据、内核、语言信息）。
notebook_export：使用 nbconvert 将笔记本导出为其他格式（例如 Python、HTML）。注意： 某些导出格式（如 PDF）所需的依赖项，请参阅下文“外部依赖项”。
notebook_get_outline：生成大纲，显示单元格编号、主要标题/函数和行数，方便 Agent 浏览大型笔记本。
notebook_search：搜索单元格中的关键词，并显示找到匹配项的单元格及其上下文摘要。这有助于 Agent 在收到修改请求时确定要读取或编辑哪个单元格。
notebook_edit_cell_output：支持直接操作和设置单元格输出。
notebook_bulk_add_cells：一次操作即可向笔记本添加多个单元格。
notebook_get_server_path_context：提供详细的服务路径配置（allowed_roots、操作系统路径风格、SFTP 状态、项目目录验证和路径构建指南）。

要求

本项目既依赖 Python 软件包，也可能需要外部系统依赖项才能完整运行。

Python 依赖项

Python 版本： 3.10+
核心依赖： mcp>=0.1.0、nbformat>=5.0、nbconvert>=6.0、ipython、jupyter_core、paramiko>=2.8.0、fastmcp>=2.7.0,<2.11、pydantic>=2.0.0,<2.12.0、uvicorn>=0.20.0、starlette>=0.25.0。安装 cursor-notebook-mcp 时会自动安装这些依赖，并为所有传输模式（stdio、Streamable HTTP、SSE）提供支持。
可选 - 开发/测试： pytest>=7.0、pytest-asyncio>=0.18、pytest-cov、pytest-timeout>=2.0.0、coveralls。从源代码检出目录运行 pip install -e ".[dev]" 进行安装。

外部系统依赖项（可选）

这些不是 Python 包。要使用某些功能，必须在系统上单独安装：

Pandoc： nbconvert 在导出为许多非 HTML 格式时需要此工具（包括导出为 PDF 的中间步骤）。请参阅 Pandoc 安装说明。
LaTeX（推荐使用 XeLaTeX）： nbconvert 将笔记本直接导出为 PDF 时需要此工具（notebook_export 使用 export_format="pdf" 时会用到 --to pdf 选项）。请参阅安装 TeX。

如果缺少这些外部依赖项，notebook_export 工具在尝试导出为依赖它们的格式（如 PDF）时可能会失败。如果计划使用这些功能，请务必安装它们。

安装

从 PyPI 安装

标准安装命令会安装支持 stdio、Streamable HTTP 和 SSE 传输模式所需的所有依赖项。

使用 pip：
```
pip install cursor-notebook-mcp
```
使用 uv：
```
uv pip install cursor-notebook-mcp
```

开发环境安装（从源代码安装）

克隆此代码库：

git clone https://github.com/jbeno/cursor-notebook-mcp.git # 或你的 fork
cd cursor-notebook-mcp

创建并激活虚拟环境（推荐）：

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

# 或使用 uv（如果已安装）
# uv venv
# source .venv/bin/activate # 在 Windows 上使用 `.venv\Scripts\activate`

以可编辑模式安装所有可选依赖项：

使用 pip：

# 以可编辑模式安装软件包及测试依赖项。
pip install -e ".[dev]"

# 以可编辑模式安装，但不包含额外的测试依赖项：
# pip install -e .

使用 uv：

# 以可编辑模式安装软件包及测试依赖项。
uv pip install -e ".[dev]"

# 以可编辑模式安装，但不包含额外的测试依赖项：
# uv pip install -e .

服务配置和 Cursor 集成

本节详细介绍如何运行 cursor-notebook-mcp 服务，以及如何配置 Cursor 使用它，具体取决于所选的传输协议。

1. Streamable HTTP 传输（推荐）

使用 Streamable HTTP 时，需要手动运行服务进程，Cursor 则通过网络连接到该服务。对于大多数涉及 Cursor 的设置，推荐使用此方法。

A. 运行服务（需要手动启动）

首先，确保已安装软件包（例如，使用 pip install cursor-notebook-mcp 或 uv pip install cursor-notebook-mcp），如果从源代码运行，还要确保已激活虚拟环境。

使用已安装的脚本：

cursor-notebook-mcp --transport streamable-http --allow-root /path/to/your/notebooks --host 127.0.0.1 --port 8080

从源代码检出目录运行（确保已安装依赖项，例如使用 pip install -e . 或 uv pip install -e .；如果还需要测试工具，则使用 .[dev]）：
```
python -m cursor_notebook_mcp.server --transport streamable-http --allow-root /path/to/your/notebooks --host 127.0.0.1 --port 8080
```
请将 /path/to/your/notebooks 替换为你希望服务访问的目录的实际路径。

B. Cursor `mcp.json` 配置

前往 Cursor 设置 > MCP > 添加新的全局 MCP 服务。或者创建或更新 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目专用）文件：

{
  "mcpServers": {
    "notebook_mcp": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

注意：请调整 host、port 和路径（/mcp 是 FastMCP 的 Streamable HTTP 默认路径）。在 Cursor 尝试连接之前，服务必须已在运行。

2. SSE 传输（传统 Web/网络）

SSE 现在被视为传统传输方式，但仍受支持。对于新的配置，首选 Streamable HTTP。使用 SSE 时，你也需要手动运行服务进程。

A. 运行服务（必须手动启动）

确保已安装软件包（例如，pip install cursor-notebook-mcp 或 uv pip install cursor-notebook-mcp）；如果从源代码运行，请确保虚拟环境处于激活状态。

使用已安装的脚本：

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

从源代码检出目录运行：

python -m cursor_notebook_mcp.server --transport sse --allow-root /path/to/your/notebooks --host 127.0.0.1 --port 8080

B. Cursor `mcp.json` 配置

前往 Cursor Settings > MCP > Add new global MCP server。或者创建或更新 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目专用）文件：

{
  "mcpServers": {
    "notebook_mcp": {
      "url": "http://127.0.0.1:8081/sse"
    }
  }
}

注意：FastMCP 的 sse 传输使用 /sse 进行握手。Cursor 尝试连接前，服务必须处于运行状态。

3. stdio 传输

使用 stdio 传输时，Cursor 会直接启动并管理服务进程。为了在 Cursor 中集成，你无需在终端中手动运行服务。Cursor 通过标准输入/输出与服务通信。

此方法要求告知 Cursor 启动服务所需的命令和参数。必须确保 Cursor 使用正确的 Python 环境，其中已安装 cursor-notebook-mcp 及其依赖项。

选项 1：使用特定虚拟环境的绝对路径（传统的 `venv` / `virtualenv`）

如果你为该工具创建了专用的 venv，此方法很可靠。

如果 cursor-notebook-mcp 脚本位于 venv 的 bin 目录中：

{
  "mcpServers": {
    "notebook_mcp": {
      "command": "/absolute/path/to/venv/bin/cursor-notebook-mcp",
      "args": [
        "--allow-root", "/absolute/path/to/your/notebooks"
      ]
    }
  }
}

使用 venv 中的 Python 运行模块：

{
  "mcpServers": {
    "notebook_mcp": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": [
        "-m", "cursor_notebook_mcp.server",
        "--allow-root", "/absolute/path/to/your/notebooks"
      ]
    }
  }
}

请相应替换 /absolute/path/to/venv/... 和 /absolute/path/to/your/notebooks。请记住，你可以根据需要在 args 列表中添加其他 cursor-notebook-mcp 参数（例如 --log-level DEBUG）。

选项 2：使用 `uv` 在特定项目的虚拟环境中运行（推荐用于由 `uv` 管理的项目）

此方法使用 uv 在指定项目的 Python 环境中执行 cursor-notebook-mcp。这种方式更可靠，因为它明确指定了 uv 的项目上下文。请确保已安装 uv。你可能需要在 command 字段中提供 uv 可执行文件的完整路径（例如，在 macOS/Linux 上运行 which uv，或在 Windows 上运行 where uv 查找路径）。为 uv --directory 指定的项目目录应为由 uv 管理环境的项目根目录（例如，uv venv 创建了 .venv 且已安装 cursor-notebook-mcp 的目录）。以下示例可用于 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目专用）。

如果 cursor-notebook-mcp 是安装在 uv 环境中的脚本：

{
  "mcpServers": {
    "notebook_mcp": {
      "command": "uv", 
      "args": [
        "--directory", "/absolute/path/to/your/project/with/uv/venv", 
        "run", "--", 
        "cursor-notebook-mcp", 
        "--allow-root", "/absolute/path/to/your/notebooks"
      ]
    }
  }
}

使用 uv run 和 python -m ...：

{
  "mcpServers": {
    "notebook_mcp": {
      "command": "uv", 
      "args": [
        "--directory", "/absolute/path/to/your/project/with/uv/venv", 
        "run", "--", 
        "python", "-m", "cursor_notebook_mcp.server",
        "--allow-root", "/absolute/path/to/your/notebooks"
      ]
    }
  }
}

注意：对于这些 uv 示例，/absolute/path/to/your/project/with/uv/venv 必须是项目的正确绝对路径，且 cursor-notebook-mcp 必须安装在该项目由 uv 管理的环境中。笔记本的 --allow-root 路径也应使用绝对路径，以确保清晰可靠。你可以根据需要，将其他 cursor-notebook-mcp 参数（如 --log-level DEBUG 或 --port 8889）添加到 args 列表末尾，作为 cursor-notebook-mcp 或 python -m cursor_notebook_mcp.server 的参数。

用于 AI 指引的 Cursor 规则

该软件包包含一个 cursor_rules.md 文件，用于在通过 MCP 服务处理 Jupyter 笔记本时校准 Agent 的行为。这些规则为 Markdown 格式、工具使用、路径解析等提供指引，确保笔记本操作一致且整洁。

默认行为：可见性与反馈

默认情况下，这些规则经过优化，可让你清楚地看到 AI 构建或修改笔记本时的操作。AI 通常会使用单独的工具调用来执行添加单元格等操作，因此你可以看到笔记本逐个单元格地构建起来。这样能提供良好的反馈，让你在需要时快速介入。不过，这种方式会产生更多工具调用，使用付费 AI 服务时可能会增加成本。

在 Cursor 中配置规则

如需使用 Cursor 规则：

打开 Cursor
前往 Cursor > Settings > Cursor Settings
点击侧边栏中的“Rules”
你可以选择以下任一方式：
- 点击“Project Rules”下的“Add new rule”，仅将规则应用于当前项目
- 添加到“User Rules”，以全局应用规则

可选：节省成本模式

如果你更关注成本效益，且不介意等待结果，可以将以下部分添加到规则中：

8. **Efficiency Mode (Cost Optimization):**
   * Minimize tool calls as they incur API costs.
   * Use `notebook_bulk_add_cells` instead of multiple `notebook_add_cell` calls when adding multiple cells.
   * Use `notebook_read` to get the full notebook state instead of reading individual cells.
   * Only use `notebook_read_cell` when you need to verify a specific cell's content.
   * Batch related changes together when possible.
   * Skip verification reads if the operation is simple and unlikely to fail.

通过 SFTP/SSH 编辑远程笔记本

此服务支持通过 SFTP（SSH 文件传输协议）访问和编辑存储在远程服务上的 Jupyter 笔记本。只要你拥有远程计算机的 SSH 访问权限，且已启用 SFTP，就可以像处理本地笔记本一样进行操作。

工作原理

服务器使用 paramiko 库建立 SSH 连接，然后创建 SFTP 会话。指定一个或多个 --sftp-root 参数后，服务器会将这些远程位置映射到内部路径。之后，所有针对这些远程根目录下路径的笔记本操作（读取、写入、列出等）都会通过 SFTP 透明处理。

前提条件

远程服务已启用 SFTP： 远程计算机上的 SSH 服务必须启用 SFTP 子系统。大多数 Linux/macOS SSH 服务默认都会启用。
SSH 访问权限： 你需要拥有远程服务的有效凭据（用户名、密码和/或 SSH 密钥）。
paramiko 依赖项： cursor-notebook-mcp 包已将 paramiko 作为核心依赖项，因此通常无需额外安装。

关于传输方式和身份验证的重要说明

对于需要交互式身份验证的 SFTP 连接（例如，密码提示、双重身份验证（2FA）/多重身份验证（MFA）验证码、SSH 密钥口令），必须使用网络传输方式（例如推荐的 streamable-http 或 sse）手动运行 cursor-notebook-mcp 服务。

这是因为这些提示会在服务启动并尝试建立 SFTP 连接时出现。如果使用 stdio 传输方式（Cursor 会在后台启动服务），你将无法与这些提示交互，连接很可能会失败。

使用网络传输方式在终端中手动运行服务时，终端会直接提示你输入所需的密码、口令或 2FA 验证码。

SFTP 命令行参数

启动服务时，使用以下命令行参数配置 SFTP 访问：

--sftp-root user@host:/path/to/remote/notebooks
- 指定远程笔记本目录。格式为 username@hostname:/absolute/path/on/server。
- 可以多次使用此参数，以映射多个不同的远程位置。
- 路径支持波浪号展开（~）（例如，user@host:~/notebooks）。
--sftp-password your_password_or_passphrase
- （可选）提供用于 SSH 密码身份验证的密码，或用于加密 SSH 私钥的口令。
- 安全说明： 直接在命令行中提供凭据可能存在安全风险（例如，凭据可能暴露在 shell 历史记录或进程列表中）。通常，更安全的做法是不使用此参数，而是在服务启动时根据交互提示输入凭据，或尽可能使用 SSH Agent／不带口令的密钥身份验证。
--sftp-key /path/to/your/private_key
- 指定 SSH 私钥文件的路径（例如，~/.ssh/id_rsa）。
--sftp-port port_number
- SFTP 连接使用的 SSH 端口。默认为 22。
--sftp-auth-mode mode：
- SFTP 身份验证模式（例如，auto、key、password、key+interactive）。默认为 auto。
--sftp-no-agent：
- 禁用使用 SSH Agent 进行 SFTP 身份验证。
--sftp-no-interactive：
- 禁用所有交互式 SFTP 身份验证提示。
--sftp-no-password-prompt：
- 如果未通过 --sftp-password 提供密码／口令，则跳过密码／口令提示，但仍允许其他交互式提示（例如，2FA 验证码）。

SFTP 配置示例

以下示例展示了如何使用各种 SFTP 身份验证方式启动 cursor-notebook-mcp 服务。请记得使用 streamable-http 等网络传输方式。

1. 密码认证

交互式提示输入密码：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/home/myuser/notebooks \
  --sftp-auth-mode password

（服务启动时，系统会提示你输入 myuser 的密码。）

通过参数提供密码（安全性较低）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/home/myuser/notebooks \
  --sftp-password "MySecretP@ssw0rd" \
  --sftp-auth-mode password

2. SSH 密钥认证

无密码短语的密钥（例如，~/.ssh/id_rsa）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/project_notebooks \
  --sftp-key ~/.ssh/id_rsa \
  --sftp-auth-mode key

带密码短语的密钥（交互式提示输入）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/srv/notebooks \
  --sftp-key ~/.ssh/encrypted_key \
  --sftp-auth-mode key

（系统会提示你输入 encrypted_key 的密码短语。）

带密码短语的密钥（通过参数提供）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/data/notebooks \
  --sftp-key ~/.ssh/encrypted_key \
  --sftp-password "MyPrivateKeyPassphrase" \
  --sftp-auth-mode key

3. 键盘交互式认证（例如，2FA/MFA）

服务提示输入用户名/密码和/或 2FA 验证码：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/notebooks \
  --sftp-auth-mode interactive

4. 组合认证：SSH 密钥（受密码短语保护）+ 键盘交互式认证（2FA/MFA）

此场景适用于 SSH 密钥经过密码短语加密，且服务还要求通过键盘交互式认证提供第二重验证（例如，TOTP 验证码）的情况。

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/notebooks \
  --sftp-key ~/.ssh/your_encrypted_rsa_key \
  --sftp-auth-mode key+interactive

（服务启动时，系统应首先提示你输入 your_encrypted_rsa_key 的密码短语。成功输入后，如果服务还要求进一步的交互式认证，系统会提示你输入 2FA 验证码或其他交互式信息。）

5. 组合认证：密码 + 键盘交互式认证（例如，先输入密码，再输入 2FA 验证码）

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/notebooks \
  --sftp-auth-mode password+interactive

（系统会提示输入密码；如果服务要求，还会接着提示输入 2FA 验证码。）

6. 使用 SSH Agent

默认情况下（--sftp-auth-mode auto 或 key），服务会尝试使用正在运行的 SSH Agent。如果密钥已加载到 Agent 中，则可能无需为密钥密码短语指定 --sftp-key 或 --sftp-password。

使用 Agent 并启用 2FA（仅通过键盘交互式认证输入 2FA 验证码）：

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:~/notebooks \
  --sftp-auth-mode auto  # 或使用 key+interactive，明确指定认证方式
  # 可选：--sftp-no-password-prompt，如果 Agent 处理密钥认证，但 2FA 提示是单独的

（假设密钥已加载到 Agent 中。如果密钥认证后服务还要求进行 2FA，系统会提示输入验证码。）

多个远程根目录

你可以多次指定 --sftp-root 以连接到不同路径；如果不同服务使用兼容的认证方式，也可以连接到不同服务（或者，如果服务支持针对每个根目录的凭据参数，则可以为每个根目录提供特定凭据；目前尚不支持此功能，因此所有连接都会尝试使用相同的全局凭据，例如指定的密码/密钥文件）。

cursor-notebook-mcp --transport streamable-http --host 0.0.0.0 --port 8080 \
  --sftp-root [email protected]:/projects/alpha \
  --sftp-root [email protected]:~/personal_notebooks \
  --sftp-key ~/.ssh/id_serverA \
  --sftp-auth-mode key

路径处理

波浪号扩展： --sftp-root 中的 ~/my_notebooks 等远程路径会扩展为远程服务上的用户主目录。
内部映射： 服务会将这些远程 SFTP 路径映射为临时的类本地表示，以供内部操作使用。在 Cursor 中，您仍可使用原始远程路径与其交互（例如，[email protected]:/home/myuser/notebooks/MyNotebook.ipynb）。
使用 notebook_get_server_path_context 了解上下文： 对于与服务交互的 AI Agent，notebook_get_server_path_context 工具尤其有用。它会提供所有已配置根目录（本地和 SFTP）的详细信息、服务的操作系统路径样式，以及路径构造和解析方式的说明。这有助于 AI 了解给定的 SFTP 路径与用户当前项目目录（如果是本地目录）的关系，并正确理解可能涉及本地和远程路径引用的用户指令。

配置好 SFTP 根目录并启动服务后，只要路径位于 --allow-root（用于本地文件）或已配置的 --sftp-root 范围内，就可以在 Cursor 中使用 notebook_mcp 工具像操作本地笔记本一样操作这些远程路径下的笔记本。

日志记录

服务会记录其操作，以帮助排查问题和进行监控。

默认日志位置： 默认情况下，日志文件存储在 ~/.cursor_notebook_mcp/server.log（.cursor_notebook_mcp 目录会在用户的主目录中创建）。
自定义日志目录： 可以使用 --log-dir 命令行参数指定其他日志文件目录。例如：cursor-notebook-mcp --allow-root /path/to/notebooks --log-dir /custom/log/path
日志级别： 可以使用 --log-level 参数控制日志的详细程度。默认日志级别为 INFO。其他可用级别包括 DEBUG、WARNING、ERROR 和 CRITICAL。将级别设为 DEBUG 对开发或深入排查问题尤其有用，因为它会显示大量输出，包括所有异常的完整堆栈跟踪（即使这些异常已由服务处理）。

命令行参数

服务接受以下命令行参数：

--allow-root：（如果未提供 --sftp-root，则为必填项，可多次使用）允许访问本地笔记本的目录的绝对路径。
--log-dir：存储日志文件的目录。默认为 ~/.cursor_notebook_mcp。
--log-level：设置日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL。默认为 INFO。
--max-cell-source-size：单元格源内容允许的最大字节数。默认为 10 MiB。
--max-cell-output-size：单元格输出内容允许的最大字节数。默认为 10 MiB。
--transport：要使用的传输类型：stdio、streamable-http 或 sse。默认为 stdio。Web 场景推荐使用 streamable-http；sse 是已弃用的替代选项。
--host：Streamable HTTP 或 SSE 服务绑定的主机。仅在 --transport=streamable-http 或 --transport=sse 时使用。默认为 127.0.0.1。
--port：Streamable HTTP 或 SSE 服务绑定的端口。仅在 --transport=streamable-http 或 --transport=sse 时使用。默认为 8080。
--sftp-root user@host:/path/to/remote/notebooks：
- 通过 SFTP 指定远程笔记本目录。可多次使用。
- 详细用法和身份验证方式请参阅“通过 SFTP/SSH 编辑远程笔记本”一节。
--sftp-password your_password_or_passphrase：
- （可选，但出于安全考虑不建议使用）提供 SSH 身份验证密码，或加密 SSH 私钥的口令。通常更安全的做法是不提供此参数，并在需要时通过交互式提示输入凭据。
--sftp-key /path/to/your/private_key：
- 用于 SFTP 身份验证的 SSH 私钥文件路径。
--sftp-port port_number：
- SFTP 连接使用的 SSH 端口。默认为 22。
--sftp-auth-mode mode：
- SFTP 身份验证模式（例如 auto、key、password、key+interactive）。默认为 auto。
--sftp-no-agent：
- 禁止使用 SSH Agent 进行 SFTP 身份验证。
--sftp-no-interactive：
- 禁止所有交互式 SFTP 身份验证提示。
--sftp-no-password-prompt：
- 如果未通过 --sftp-password 提供密码或口令，则跳过相应提示，但允许其他交互式提示（例如双重身份验证代码）。

安全

工作区根目录强制检查： 服务启动时要求提供 --allow-root 命令行参数。对于位于这些参数指定目录之外的任何笔记本文件，服务都会拒绝操作。这是一项关键的安全边界。
路径处理： 服务使用 os.path.realpath 解析路径，并在执行任何读取或写入操作之前检查路径是否位于允许的根目录中。
SFTP 身份验证安全性： 通过 SFTP 连接远程笔记本时，强烈建议使用网络传输方式（streamable-http 或 sse）。这样，服务就可以在终端中以交互方式提示你输入密码、SSH 密钥口令或双重身份验证（2FA）代码等凭据。与通过命令行参数（例如 --sftp-password）提供敏感信息相比，这种方式更安全，因为它可以避免凭据暴露在 shell 历史记录或系统进程列表中。服务利用这些交互式提示支持多种身份验证流程，包括证书 + 2FA 或密码 + 2FA 等多重验证组合。
输入验证： 会对 .ipynb 扩展名进行基本检查。
单元格源内容大小限制： 服务会对提供给 notebook_edit_cell 和 notebook_add_cell 的源内容强制执行最大大小限制（可通过 --max-cell-source-size 配置，默认值为 10 MiB），以防止内存使用过量。
单元格输出大小限制： 服务会对 notebook_read_cell_output 返回的输出总序列化大小强制执行最大大小限制（可通过 --max-cell-output-size 配置，默认值为 10 MiB）。

限制

无法执行单元格： 此服务无法执行笔记本单元格。它仅使用 nbformat 库操作 .ipynb 文件结构，不会与 Jupyter 内核交互。必须由用户在 Cursor UI 中手动执行单元格（选择所需的内核并运行单元格）。

问题

如果你遇到 bug、有功能请求或其他问题，请查看现有问题，或在我们的 GitHub 问题跟踪器中提交新问题。

已知问题

请查看 GitHub Issues 页面，了解目前已知问题列表。

UI 刷新问题： 有时，某些笔记本操作（例如拆分或合并单元格）可能已在文件层面成功完成，但 Cursor UI 可能无法正确显示更新后的内容。在这种情况下，你可以：
- 关闭并重新打开笔记本文件
- 保存文件；系统可能会提示“Revert”或“Overwrite”，选择“Revert”以重新加载实际文件内容
不支持检查点： Agent 使用第三方 MCP 工具进行编辑时，不会在 AI 聊天记录中注册检查点，也不会显示“Restore Checkpoint”按钮。为降低风险：
- 经常使用 git 提交，以便回滚
- 在关键里程碑手动创建工作副本
没有文件／行上下文： Cursor 不会像处理其他文件那样自动共享 Jupyter 笔记本上下文。对于其他文件（Python、Markdown），它会与 AI Agent 共享当前文件和行号。但对于笔记本，它不会共享任何上下文。理想情况下，它应该共享单元格以及该单元格中的行号。可以通过以下方式解决：
- 知道要编辑的单元格、函数或部分时，尽量明确说明
- Agent 可以使用 notebook_get_outline 获取笔记本的大致大纲，帮助它识别包含关键类、函数或 Markdown 标题的单元格。
- Agent 可以使用 notebook_search 确定哪些单元格包含关键词、类或函数。

提交问题

提交新问题：

访问 jbeno/cursor-notebook-mcp Issues 页面。
点击“New Issue”。
提供：
- 对问题或功能请求的清晰描述。
- 重现问题的步骤（如适用）。
- 预期行为与实际行为。
- 环境详情（操作系统、Python 版本、cursor-notebook-mcp 版本等）。
- 任何相关错误消息或日志。
- 所使用的模型和客户端/版本（如果与 AI 交互相关）。

贡献

欢迎为改进 Jupyter Notebook MCP 服务贡献力量！

如果你想参与贡献，请先 Fork 此仓库，为你的更改创建一个分支，然后向 jbeno/cursor-notebook-mcp 的 main 分支提交 Pull Request（PR）。

请确保你的更改包含：

新功能对应的单元测试。
如果更改会影响用法或添加功能，请更新文档（README.md、CHANGELOG.md）。
遵循现有代码风格。

提交 PR 前，请运行测试脚本（./run_tests.sh 或 .\run_tests.ps1），确保所有测试均通过。

重大更改讨论： 对于重要更改或新功能，建议先提交问题，讨论拟议的更改，并确认其符合项目目标。

开发环境设置

首先，克隆仓库并设置虚拟环境。然后以可编辑模式安装软件包，以及所有开发和测试依赖项：

使用 pip：

# From the project root directory
python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
pip install -e ".[dev]"

使用 uv：

# From the project root directory
uv venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
uv pip install -e ".[dev]"

运行单元测试

本项目使用 pytest 进行单元测试。测试文件位于 tests/ 目录中。添加新测试时，请将其放在此目录中，并遵循现有命名约定（例如，test_*.py）。

运行测试时，请使用提供的包装脚本。这些脚本会逐个运行测试文件，有助于避免直接对本项目的所有测试文件运行 pytest 时可能出现的卡住问题，尤其是在涉及异步操作或 SFTP 测试时。

在 Linux/macOS 上： 使用包装脚本，确保正确设置环境变量。

./run_tests.sh 
# To run specific tests:
# ./run_tests.sh tests/test_notebook_tools.py

在 Windows 上： 使用 PowerShell 包装脚本。

.\run_tests.ps1
# To run specific tests:
# .\run_tests.ps1 tests/test_notebook_tools.py

代码覆盖率

通过包装脚本（run_tests.sh 或 run_tests.ps1）运行测试时，会使用 pytest-cov 自动计算代码覆盖率。

详细的覆盖率报告可在 Coveralls 上查看。你可以通过本 README 顶部的徽章查看当前覆盖率状态，也可以直接访问 https://coveralls.io/github/jbeno/cursor-notebook-mcp?branch=main。

AI 驱动的测试计划（`test_plan.md`）

除了自动化单元测试外，仓库还包含一个 test_plan.md 文件。该文档列出了一系列基于场景的测试，供 AI Agent 执行，例如处于 Agent Mode 的 Cursor，或其他可访问 notebook_mcp 工具的对话式 AI。

如需使用，可指示 AI Agent“执行 test_plan.md 中的测试计划”。该计划涵盖了多种笔记本操作，从基本编辑到 SFTP 访问和元数据更改，可帮助验证这些工具在真实、多步骤工作流中的实用性和正确性。测试计划中的说明考虑了不同的操作系统（macOS/Linux 或 Windows）。

许可证

本项目采用 Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License 许可。详情请参阅 LICENSE 文件。

本作品采用 Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License 许可。

作者

本项目由 Jim Beno 创建并维护 - [email protected]

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Jupyter Notebook MCP Server (for Cursor)

关于 Jupyter Notebook MCP Server (for Cursor)

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

Jupyter Notebook MCP 服务（适用于 Cursor）

最新版本

视频演示

Notebook MCP Server 0.3.0 更新（YouTube）

Notebook MCP Server 概览（YouTube）

功能

要求

Python 依赖项

外部系统依赖项（可选）

安装

从 PyPI 安装

开发环境安装（从源代码安装）

服务配置和 Cursor 集成

1. Streamable HTTP 传输（推荐）

A. 运行服务（需要手动启动）

B. Cursor mcp.json 配置

2. SSE 传输（传统 Web/网络）

A. 运行服务（必须手动启动）

B. Cursor mcp.json 配置

3. stdio 传输

选项 1：使用特定虚拟环境的绝对路径（传统的 venv / virtualenv）

选项 2：使用 uv 在特定项目的虚拟环境中运行（推荐用于由 uv 管理的项目）

用于 AI 指引的 Cursor 规则

默认行为：可见性与反馈

在 Cursor 中配置规则

可选：节省成本模式

通过 SFTP/SSH 编辑远程笔记本

工作原理

前提条件

关于传输方式和身份验证的重要说明

SFTP 命令行参数

SFTP 配置示例

1. 密码认证

2. SSH 密钥认证

3. 键盘交互式认证（例如，2FA/MFA）

4. 组合认证：SSH 密钥（受密码短语保护）+ 键盘交互式认证（2FA/MFA）

5. 组合认证：密码 + 键盘交互式认证（例如，先输入密码，再输入 2FA 验证码）

6. 使用 SSH Agent

多个远程根目录

路径处理

日志记录

命令行参数

安全

限制

问题

已知问题

提交问题

贡献

开发环境设置

运行单元测试

代码覆盖率

AI 驱动的测试计划（test_plan.md）

许可证

作者

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

B. Cursor `mcp.json` 配置

B. Cursor `mcp.json` 配置

选项 1：使用特定虚拟环境的绝对路径（传统的 `venv` / `virtualenv`）

选项 2：使用 `uv` 在特定项目的虚拟环境中运行（推荐用于由 `uv` 管理的项目）

AI 驱动的测试计划（`test_plan.md`）