Jupyter Notebook MCP Server

关键词

Jupyter NotebookLLM 交互代码执行数据分析自动化

项目简介

Jupyter Notebook MCP Server 是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在桥接 LLM 客户端（如 Claude AI）和 Jupyter Notebook。它允许 LLM 通过标准化的 MCP 协议与 Jupyter Notebook 进行交互，执行代码、分析数据、可视化等操作，从而实现 AI 辅助的 Notebook 自动化和增强功能。

兼容性警告： 该工具仅兼容 Jupyter Notebook v6.x 版本，不支持 Jupyter Lab, Jupyter Notebook v7.x, VS Code Notebooks, Google Colab 等其他Notebook 界面。

主要功能点

  • 双向通信: 通过 WebSocket 服务器在 LLM 客户端和 Jupyter Notebook 之间建立双向通信。
  • Notebook 控制: 支持 LLM 客户端远程控制 Jupyter Notebook，包括：
    • 单元格操作: 插入、执行和管理 Notebook 单元格。
    • Notebook 管理: 保存 Notebook、获取 Notebook 信息。
    • 代码执行: 运行指定单元格或全部单元格，并获取执行结果。
    • 输出检索: 获取单元格的文本和图像输出。
    • 单元格编辑: 编辑单元格内容。
    • 幻灯片设置: 设置单元格的幻灯片类型，用于演示文稿。

安装步骤

  1. 环境准备:

    • 确保已安装 Python 3.12 或更高版本。
    • 安装 'uv' 包管理器（参考仓库 README 获取安装指南）。
    • 建议安装 Claude AI 桌面应用程序 以配合使用 (虽然可以使用其他MCP客户端)。

  2. 克隆仓库:

    git clone https://github.com/jjsantos01/jupyter-notebook-mcp.git
cd jupyter-notebook-mcp

  3. 创建虚拟环境并安装内核:

    uv run python -m ipykernel install --name jupyter-mcp

  4. (可选) 安装其他 Python 包:

    uv pip install seaborn  # 例如安装 seaborn

  5. 配置 Claude 桌面应用 (或其他MCP客户端): 打开 Claude 桌面应用的配置 'claude_desktop_config.json' 文件（'Claude' > 'Settings' > 'Developer' > 'Edit Config'）。在 'mcpServers' 中添加 'jupyter' 服务器配置。

    {
    "mcpServers": {
        "jupyter": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/src", // 替换为仓库 src 文件夹的绝对路径
                "run",
                "jupyter_mcp_server.py"
            ]
        }
    }
}

    注意: '/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/src' 需要替换为你本地 'jupyter-notebook-mcp' 仓库 'src' 文件夹的绝对路径。例如：

    • Windows: '"C:\Users\YourUserName\GitHub\jupyter-notebook-mcp\src"'
    • macOS/Linux: '"/Users/YourUserName/GitHub/jupyter-notebook-mcp/src"'

    保存 'claude_desktop_config.json' 文件后，重启 Claude 桌面应用使配置生效。

基本使用方法

  1. 启动 Jupyter Notebook (v6.x):

    uv run jupyter nbclassic

  2. 创建并配置 Notebook:

    • 新建 Jupyter Notebook，务必选择 'jupyter-mcp' 内核 ('Kernel' -> 'Change kernel' -> 'jupyter-mcp')。

    • 在 Notebook 单元格中运行以下 Python 代码以启动 WebSocket 服务器：

      import sys
sys.path.append('/path/to/jupyter-notebook-mcp/src')  # 替换为仓库 src 文件夹的路径

from jupyter_ws_server import setup_jupyter_mcp_integration

server, port = setup_jupyter_mcp_integration()
print(f"WebSocket server started on port: {port}") # 打印 WebSocket 服务器端口

      注意: ''/path/to/jupyter-notebook-mcp/src'' 同样需要替换为你本地 'jupyter-notebook-mcp' 仓库 'src' 文件夹的相对或绝对路径。

  3. 连接 Claude (或其他MCP客户端): 启动配置了 'jupyter' MCP 服务器的 Claude 桌面应用。Claude 将自动连接到 Jupyter Notebook 的 MCP 服务器。

  4. 通过 Claude 与 Jupyter Notebook 交互: 在 Claude 中，你可以使用自然语言指令指示其操作 Jupyter Notebook。例如，可以使用示例 Prompt 来创建演示文稿或执行数据分析任务。

外部客户端测试 (可选)

你可以使用仓库自带的外部客户端测试工具来验证 MCP 服务器的功能，无需 Claude 客户端：

uv run python src/jupyter_ws_external_client.py

或运行批量自动化测试：

uv run python src/jupyter_ws_external_client.py --batch

服务器信息

访问项目