该服务器允许兼容的 AI 助手（如 Cursor 或 Claude Desktop）与本地计算机上的 Jupyter Notebook 文件（.ipynb）进行交互。
📋 先决条件
开始之前，请确保已安装以下软件：
- Python： 3.10 或更高版本。
uv ： Astral 提供的快速 Python 软件包安装程序和虚拟环境管理器。如果您还没有安装，请安装：# On macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# IMPORTANT: Add uv to your PATH if prompted by the installer
# For macOS/Linux (bash/zsh), add to your ~/.zshrc or ~/.bashrc:
# export PATH="$HOME/.local/bin:$PATH"
# Then restart your shell or run `source ~/.zshrc` (or equivalent)
- **
fastmcp CLI（可选，用于 Claude Desktop fastmcp install ）：**如果您计划使用fastmcp install方法安装 Claude Desktop，则需要fastmcp命令。# Using uv
uv pip install fastmcp
# Or using pipx (recommended for CLI tools)
pipx install fastmcp
🔧 设置
- 克隆存储库：
git clone https://github.com/UsamaK98/python-notebook-mcp.git # Or your fork/local path
cd python-notebook-mcp
- 选择设置方法：
- **选项 A：自动设置（推荐）**从项目的根目录（您刚刚通过
cd进入的位置）运行适合您操作系统的脚本。- macOS / Linux：
# Make script executable (if needed)
chmod +x ./install_unix.sh
# Run the script
bash ./install_unix.sh
- Windows（PowerShell）：GXP5 这些脚本将创建
.venv 、安装依赖项并输出 MCP 客户端配置所需的精确路径。
- 选项 B：手动设置如果您喜欢手动控制或遇到脚本问题，请按照以下步骤操作。
- 创建并激活虚拟环境：
# Create the environment (e.g., named .venv)
uv venv
# Activate the environment
# On macOS/Linux (bash/zsh):
source .venv/bin/activate
# On Windows (Command Prompt):
# .venv\Scripts\activate.bat
# On Windows (PowerShell):
# .venv\Scripts\Activate.ps1
(.venv)或类似内容） - 安装依赖项：
# Make sure your venv is active
uv pip install -r requirements.txt
▶️ 运行服务器
如果您使用手动设置，请确保您的虚拟环境（ .venv ）已激活。
方法一：直接执行（推荐用于Cursor，一般用途）
此方法使用uv run直接使用您当前的 Python 环境（现在应该已安装依赖项）执行服务器脚本。
- 运行服务器：
# From the python-notebook-mcp directory
uv run python server.py
- **客户端配置 (
mcp.json )：**配置您的 MCP 客户端（例如 Cursor）进行连接。创建或编辑客户端的 MCP 配置文件（例如，您工作区中的.cursor/mcp.json ）。模板（推荐）：{
"mcpServers": {
"jupyter": {
// Use the absolute path to the Python executable inside your .venv
"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": [
// Absolute path to the server script
"/full/absolute/path/to/python-notebook-mcp/server.py"
],
"autoApprove": ["initialize_workspace"] // Optional: Auto-approve certain safe tools
}
}
}
❓ 为什么要使用 Python 的完整路径？像 Cursor 这样的 GUI 应用程序可能不会继承与终端相同的PATH环境变量。在.venv文件中指定 Python 解释器的精确路径，可以确保服务器以正确的环境变量和依赖项运行。⚠️重要提示：请将占位符路径替换为系统上的实际绝对路径。
方法 2：Claude 桌面集成（ fastmcp install ）
此方法使用fastmcp工具为服务器创建一个专用的、隔离的环境，并将其注册到 Claude Desktop。通常情况下，您无需手动激活.venv文件，因为fastmcp install会处理环境的创建。
- 为 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 Dev 模式：**用于与 MCP Inspector 进行交互式测试：
# Make sure fastmcp is installed in your environment
# uv pip install fastmcp
uv run fastmcp dev server.py
📄 许可证
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。