关键词

Jupyter NotebookAI集成代码笔记本LLM工具

项目简介

'python-notebook-mcp' 是一个实现了 Model Context Protocol (MCP) 的服务器应用，专门用于让兼容的 AI 助手（如 Cursor, Claude Desktop 等）能够与您本地文件系统中的 Jupyter Notebook ('.ipynb') 文件进行交互。它允许 AI 助手读取、编辑、创建 Notebook 文件，并获取单元格内容和输出。

主要功能点

本项目作为一个MCP服务器，提供了以下核心功能：

  • 工作空间初始化: 设定AI助手可以操作的 Notebook 文件所在的根目录。
  • 列出 Notebooks: 查找并列出工作空间目录下的所有 '.ipynb' 文件。
  • 创建 Notebook: 在指定路径创建一个新的空白 Jupyter Notebook 文件。
  • 读取 Notebook: 获取整个 Notebook 文件的结构和所有单元格的内容。
  • 读取单元格: 根据索引获取 Notebook 中特定单元格的内容和元数据。
  • 编辑单元格: 修改 Notebook 中特定单元格的源代码内容。
  • 添加单元格: 在指定位置或末尾向 Notebook 添加新的代码或 Markdown 单元格。
  • 读取 Notebook 输出: 获取 Notebook 中所有代码单元格的执行输出。
  • 读取单元格输出: 获取 Notebook 中特定代码单元格的执行输出。

安装步骤

本项目需要 Python 3.10 或更高版本。推荐使用 'uv' 进行包管理和虚拟环境创建。

  1. 安装 'uv': 如果没有安装，请参考项目 README 或 'uv' 官方文档安装。

    # macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

    （请确保将 'uv' 添加到您的系统 PATH 环境变量中）

  2. 克隆仓库:

    git clone https://github.com/UsamaK98/python-notebook-mcp.git
cd python-notebook-mcp

  3. 运行安装脚本 (推荐):

    • macOS / Linux: 
      chmod +x ./install_unix.sh
bash ./install_unix.sh
    • Windows (PowerShell): 
      .\install_windows.ps1

    脚本将创建虚拟环境、安装依赖，并输出后续配置 MCP 客户端所需的Python 可执行文件路径和服务器脚本路径。请务必记录下这些路径。

  4. 手动安装 (备选):

    # 创建并激活虚拟环境
uv venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1

# 安装依赖
uv pip install -r requirements.txt

    手动安装后，您需要自行找到虚拟环境内 Python 可执行文件的绝对路径以及仓库克隆目录内 'server.py' 文件的绝对路径。

服务器配置 (客户端 'mcp.json' 配置示例说明)

MCP 服务器不是一个独立运行的后台服务，而是由 MCP 客户端（如 AI 助手）根据配置按需启动和停止的进程。您需要在您的 MCP 客户端（通常是 AI 助手应用）的配置文件（通常命名为 'mcp.json' 或类似文件）中配置此服务器。

配置信息是一个 JSON 对象，通常位于一个名为 'mcpServers' 的顶级键下。您需要为此服务器定义一个名称（例如 '"jupyter"'），然后在这个名称对应的对象中提供启动服务器的指令。

关键配置项包括：

  • '"command"': 这个值应该是启动此 MCP 服务器的 绝对路径。如果您使用了安装脚本或手动创建了虚拟环境，这个路径应指向您虚拟环境内 Python 可执行文件的绝对路径（例如 '/home/user/python-notebook-mcp/.venv/bin/python' 或 'C:\Users\User\python-notebook-mcp.venv\Scripts\python.exe'）。直接使用 'python' 命令可能无法在 AI 助手的环境中找到正确的 Python 环境，强烈建议使用绝对路径。
  • '"args"': 这是一个 JSON 数组，包含传递给 'command' 命令的参数。对于此服务器，第一个参数应该是 'server.py' 文件的绝对路径（例如 '/home/user/python-notebook-mcp/server.py' 或 'C:\Users\User\python-notebook-mcp\server.py'）。

配置示例结构（请根据您的系统和安装路径填写实际的绝对路径）：

{
  "mcpServers": {
    "您自定义的服务器名称, 例如 jupyter": {
      // 指向虚拟环境内的 Python 可执行文件的绝对路径
      "command": "/path/to/your/python-notebook-mcp/.venv/bin/python",
      // 指向 server.py 脚本文件的绝对路径
      "args": [
          "/path/to/your/python-notebook-mcp/server.py"
      ],
      // 可选：配置自动批准的安全工具
      "autoApprove": ["initialize_workspace"] 
    }
  }
}

请将上述 '/path/to/your/python-notebook-mcp/...' 替换为您系统上的实际绝对路径。这些路径通常在运行安装脚本后会输出，或者您可以在手动激活虚拟环境后通过 'which python' (Linux/macOS) 或 'Get-Command python' (Windows PowerShell) 找到 Python 路径，并通过文件浏览器找到 'server.py' 的路径。

将这个配置信息添加到您的 AI 助手的 MCP 配置文件中，并确保 AI 助手已启用此 MCP 服务器。

基本使用方法

连接配置完成后，通过 AI 助手与此 MCP 服务器交互的第一步必须是调用 'initialize_workspace' 工具。这个工具需要您提供您存放 Notebook 文件的项目文件夹的绝对路径。

例如，通过 AI 助手调用（具体的调用语法取决于您的 AI 助手客户端）：

initialize_workspace(directory="/full/absolute/path/to/your/project_folder")

请注意，这里必须使用绝对路径，不能使用相对路径如 '.' 或 './'。成功设置工作空间后，您就可以调用其他工具（如 'list_notebooks', 'read_notebook', 'edit_cell' 等）来操作该目录及其子目录下的 Notebook 文件了。

后续操作只需通过 AI 助手调用相应的工具即可。

信息

分类

AI与计算

访问项目