Python笔记本MCP

此服务器允许兼容的AI助手（如Cursor或Claude Desktop）与您本地机器上的Jupyter笔记本文件（.ipynb）进行交互。

📋 前提条件

开始之前，请确保已安装以下内容：

1. Python： 版本3.10或更高。
2. uv： 来自Astral的快速Python包安装程序和虚拟环境管理器。如果您还没有安装它，请按照以下步骤安装：

   # 在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中
   # 对于macOS/Linux (bash/zsh)，请将其添加到~/.zshrc或~/.bashrc:
   # export PATH="$HOME/.local/bin:$PATH"
   # 然后重启您的shell或运行 `source ~/.zshrc` （或等效命令）
   

3. fastmcp CLI（可选，用于Claude Desktop的fastmcp install）： 如果您打算使用fastmcp install方法为Claude Desktop安装，则需要fastmcp命令可用。

   # 使用uv
   uv pip install fastmcp
   
   # 或者使用pipx（推荐用于CLI工具）
   pipx install fastmcp
   

🔧 设置

1. 克隆仓库:

   git clone https://github.com/UsamaK98/python-notebook-mcp.git # 或者使用你的分叉/本地路径
   cd python-notebook-mcp
   

2. 选择设置方法:

   • 选项 A: 自动化设置（推荐）
     从项目的根目录（你刚刚 cd 进入的目录）运行适合你操作系统的脚本。

     • macOS / Linux:

       # 使脚本可执行（如果需要）
       chmod +x ./install_unix.sh
       # 运行脚本
       bash ./install_unix.sh
       

     • Windows (PowerShell):

       # 你可能需要先调整 PowerShell 的执行策略
       # Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
       .\install_windows.ps1
       

     这些脚本将创建 .venv，安装依赖项，并输出 MCP 客户端配置所需的精确路径。

   • 选项 B: 手动设置
     如果你更喜欢手动控制或在使用脚本时遇到问题，请按照以下步骤操作。

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

        # 创建环境（例如，命名为 .venv）
        uv venv
        
        # 激活环境
        # 在 macOS/Linux (bash/zsh) 上:
        source .venv/bin/activate
        # 在 Windows (命令提示符) 上:
        # .venv\Scripts\activate.bat
        # 在 Windows (PowerShell) 上:
        # .venv\Scripts\Activate.ps1
        

        (你应该会在 shell 提示符开头看到 (.venv) 或类似内容)
     2. 安装依赖项:

        # 确保你的虚拟环境已激活
        uv pip install -r requirements.txt
        

▶️ 运行服务器

如果你使用了手动设置，请确保你的虚拟环境（.venv）已激活。

方法 1: 直接执行（推荐用于光标、常规使用）

此方法使用 uv run 直接使用当前 Python 环境（此时应已安装好依赖项）来执行服务器脚本。

1. 运行服务器：

   # 从 python-notebook-mcp 目录下
   uv run python server.py
   

   服务器将启动并打印状态消息，包括（未初始化的）工作区目录。

2. 客户端配置 (mcp.json)： 配置您的 MCP 客户端（例如 Cursor）以连接。创建或编辑客户端的 MCP 配置文件（例如，工作区中的 .cursor/mcp.json）。

   模板（推荐）：

   {
     "mcpServers": {
       "jupyter": {
         // 使用 .venv 中 Python 可执行文件的绝对路径
         "command": "/full/absolute/path/to/python-notebook-mcp/.venv/bin/python", // macOS/Linux
         // "command": "C:\\full\\absolute\\path\\to\\python-notebook-mcp\\.venv\\Scripts\\python.exe", // Windows
         "args": [
             // 服务器脚本的绝对路径
             "/full/absolute/path/to/python-notebook-mcp/server.py"
           ],
         "autoApprove": ["initialize_workspace"] // 可选：自动批准某些安全工具
       }
     }
   }
   

   ❓ 为什么需要 Python 的完整路径？ 像 Cursor 这样的 GUI 应用程序可能不会继承与终端相同的 PATH 环境。指定 .venv 内部 Python 解释器的确切路径确保服务器在正确的环境和依赖项下运行。
   ⚠️ 重要提示： 将占位符路径替换为您系统上的实际绝对路径。

方法 2：Claude 桌面集成 (fastmcp install)

此方法使用 fastmcp 工具为服务器创建一个专用的隔离环境，并将其注册到 Claude 桌面。通常情况下，您不需要手动激活 .venv，因为 fastmcp install 会处理环境创建。

1. 为 Claude 安装服务器：

   # 从 python-notebook-mcp 目录下
   fastmcp install server.py --name "Jupyter Notebook MCP"
   

   • fastmcp install 在幕后使用 uv 创建环境并从 requirements.txt 安装依赖项。
   • 服务器现在将出现在 Claude 桌面开发者设置中，并可以在那里启用。通常情况下，使用 fastmcp install 时不需要手动编辑 claude_desktop_config.json。

📘 使用

关键概念：工作区初始化

无论您如何运行服务器，您必须从 AI 助手中采取的第一个操作是初始化工作区。这告诉服务器您的项目文件和笔记本的位置。

# Example tool call from the client (syntax may vary)
initialize_workspace(directory="/full/absolute/path/to/your/project_folder")

⚠️ 您必须提供包含笔记本的目录的完整绝对路径。不接受相对路径或类似 . 的路径。服务器将确认路径并列出找到的所有现有笔记本。

核心操作

一旦工作区被初始化，您可以使用可用的工具：

# List notebooks
list_notebooks()

# Create a new notebook
create_notebook(filepath="analysis/new_analysis.ipynb", title="My New Analysis")

# Add a code cell to the notebook
add_cell(filepath="analysis/new_analysis.ipynb", content="import pandas as pd\ndf = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})\ndf.head()", cell_type="code")

# Read the first cell (index 0)
read_cell(filepath="analysis/new_analysis.ipynb", cell_index=0)

# Edit the second cell (index 1)
edit_cell(filepath="analysis/new_analysis.ipynb", cell_index=1, content="# This is updated markdown")

# Read the output of the second cell (index 1) after execution (if any)
read_cell_output(filepath="analysis/new_analysis.ipynb", cell_index=1)

# Read the entire notebook structure
read_notebook(filepath="analysis/new_analysis.ipynb")

🛠️ 可用工具

🧪 开发与调试

如果您需要调试服务器本身：

• 直接运行： 使用 uv run python server.py 并观察终端输出中的错误或打印语句。
• FastMCP 开发模式： 用于与 MCP Inspector 进行交互式测试：

  # 确保在您的环境中安装了 fastmcp
  # uv pip install fastmcp
  uv run fastmcp dev server.py
  

📄 许可证

此项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。