Python notebook

此服务允许兼容的 AI 助手（如 Cursor 或 Claude Desktop）与本地计算机上的 Jupyter Notebook 文件（.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）： 如果计划在 Claude Desktop 中使用 fastmcp install 方法，则需要确保可以使用 fastmcp 命令。

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

🔧 安装

1. 克隆仓库：

   git clone https://github.com/UsamaK98/python-notebook-mcp.git # 或你的 fork/本地路径
   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. 安装依赖项：

        # 确保 venv 处于激活状态
        uv pip install -r requirements.txt
        

▶️ 运行服务

如果你采用手动安装，请确保虚拟环境（.venv）已激活。

方法 1：直接执行（推荐用于 Cursor 和一般用途）

此方法使用 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 解释器的准确路径，可确保服务使用正确的环境和依赖项运行。 ⚠️ IMPORTANT： 将占位路径替换为系统中的实际绝对路径。

方法 2：Claude Desktop 集成（fastmcp install）

此方法使用 fastmcp 工具为服务创建专用的隔离环境，并将其注册到 Claude Desktop。通常无需手动激活 .venv，因为 fastmcp install 会处理环境创建。

1. 为 Claude 安装服务：

   # From the python-notebook-mcp directory
   fastmcp install server.py --name "Jupyter Notebook MCP"
   

   • fastmcp install 会在后台使用 uv 创建环境，并从 requirements.txt 安装依赖项。
   • 服务现在会显示在 Claude Desktop 的开发者设置中，你可以在那里启用它。使用 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")

🛠️ 可用工具

工具	描述
initialize_workspace	**必需的第一步。**设置工作区的绝对路径。
list_notebooks	列出工作区目录中找到的所有 .ipynb 文件。
create_notebook	如果笔记本不存在，则创建一个新的空白 Jupyter 笔记本。
read_notebook	读取笔记本的完整结构和内容。
read_cell	按索引读取特定单元格的内容和元数据。
edit_cell	按索引修改现有单元格的源内容。
add_cell	在指定索引处或末尾添加一个新的代码或 Markdown 单元格。
read_notebook_outputs	读取笔记本中所有代码单元格的全部输出。
read_cell_output	按索引读取特定代码单元格的输出。

🧪 开发与调试

如果需要调试服务本身：

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

  # Make sure fastmcp is installed in your environment
  # uv pip install fastmcp
  uv run fastmcp dev server.py
  

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。