STARWARCLOUD STARWAR.AI
返回市场
游标笔记本-MCP

游标笔记本-MCP

作者：jbeno135 星标更新：2025-11-08
安装使用来源：spider==github.com

项目介绍

技术文档摘要

PyPI 版本 PyPI 下载量 总下载量 许可证：CC BY-NC-SA 4.0 Python 版本 GitHub 问题 最近提交 覆盖率状态

Jupyter Notebook MCP服务器（适用于Cursor）

此目录包含一个模型上下文协议（MCP）服务器，旨在允许Cursor中的AI代理与Jupyter Notebook（.ipynb）文件进行交互。它是为了克服Cursor的一个限制而创建的。截至版本0.50.5，在代理模式下，模型无法响应AI聊天面板中的对话来编辑笔记本或笔记本单元格。这为代理提供了一套MCP工具，允许直接操作笔记本单元格。

虽然设计目的是为了克服Cursor的限制，但除了配置说明外，这个MCP服务器并没有特定于Cursor的内容。你可以轻松地将其配置为与VS Code（Insiders）或Claude Code或其他能够利用MCP的模型/代理一起使用。请注意，VS Code（Insiders）现在对Jupyter Notebook的支持非常好。

该MCP服务器使用nbformat库安全地操作笔记本结构，并通过限制操作到用户定义的目录来确保安全性。它还使用nbconvert来支持将笔记本导出为各种格式，如Python脚本、HTML等。服务器通过一个干净的API处理所有笔记本操作，以维护笔记本的完整性并防止格式错误的变化。

最新版本

当前版本: 0.3.2 - 有关最近更改的详细信息，请参阅CHANGELOG.md。此版本包括对pydantic 2.12.0+兼容性的修复。之前的添加包括SFTP支持、可流传输HTTP传输以及新的工具如notebook_edit_cell_output、notebook_bulk_add_cells和notebook_get_server_path_context，以改进笔记本编辑和路径处理。

视频演示

Notebook MCP Server 0.3.0 更新 (YouTube)

最新版本缩略图

  • 0.3.0版本的更新，新工具概述
  • FastMCP升级，带有可流传输HTTP传输
  • 远程SSH服务器上编辑Jupyter笔记本的SFTP支持
  • 解决问题（#2，#4，#5）以及已知问题（#1，#3）

Notebook MCP Server 概述 (YouTube)

视频演示缩略图

  • 在Cursor中直接编辑笔记本的当前限制。
  • 安装和配置Notebook MCP Server。
  • 从零开始创建笔记本（示例：在不到两分钟内完成奇异值分解教程）。
  • 展示各种编辑工具（编辑、拆分、复制单元格）。
  • 阅读笔记本元数据。
  • 将笔记本导出为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: 生成一个大纲，显示带有主要标题/函数和行数的单元格编号，以便代理更容易导航大型笔记本。
  • notebook_search: 在单元格中搜索关键字，显示找到的匹配单元格及其上下文片段。这有助于代理知道何时需要阅读或编辑哪个单元格。
  • notebook_edit_cell_output: 允许直接操作和设置单元格输出。
  • notebook_bulk_add_cells: 在单个操作中向笔记本添加多个单元格。
  • notebook_get_server_path_context: 提供详细的服务器路径配置（允许的根目录、操作系统路径样式、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时自动安装的，并且支持所有传输模式（标准I/O、可流传输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（--to pdf选项用于notebook_export，export_format="pdf"）。请参阅安装TeX。

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

安装

从PyPI

标准安装命令将安装所有必要的依赖项，以支持标准I/O、可流传输HTTP和SSE传输模式。

  • 使用pip: 
    pip install cursor-notebook-mcp
  • 使用uv: 
    uv pip install cursor-notebook-mcp

开发安装（从源代码）

  1. 克隆此存储库：

    git clone https://github.com/jbeno/cursor-notebook-mcp.git # 或者您的分支
cd cursor-notebook-mcp

  2. 创建并激活虚拟环境（建议）：

    # 使用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`

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

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

# 以可编辑模式安装，不带额外的测试依赖项：
# pip install -e .
    • 使用uv: 
      # 以可编辑模式安装包及测试依赖项。
uv pip install -e ".[dev]"

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

服务器配置和Cursor集成

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

1. 可流传输HTTP传输（推荐）

使用可流传输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
  • 从源代码检查运行: 
    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的可流传输HTTP默认路径）。服务器必须在Cursor尝试连接之前运行。

2. SSE传输（旧版Web/网络）

SSE现在被认为是旧版传输，但仍受支持。对于新设置，推荐使用可流传输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设置 > MCP > 添加新的全局MCP服务器。或者创建或更新您的~/.cursor/mcp.json（全局）或.cursor/mcp.json（项目特定）文件：

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

注意：FastMCP的sse传输使用/sse进行握手。服务器必须在Cursor尝试连接之前运行。

3. 标准I/O传输

使用stdio传输，Cursor直接启动和管理服务器进程。您不需要在终端中手动运行服务器以进行Cursor集成。Cursor通过标准输入/输出与其通信。

这种方法要求告诉Cursor启动服务器的命令和参数。必须小心确保Cursor使用了正确安装了cursor-notebook-mcp及其依赖项的Python环境。

选项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必须是您项目的正确绝对路径，其中