Jupyter_MCP_Server

JupyterMCP - Jupyter Notebook 模型上下文协议集成

JupyterMCP 通过模型上下文协议 (MCP) 将 Jupyter Notebook 连接到 Claude AI，允许 Claude 直接与 Jupyter Notebook 交互和控制。这种集成实现了 AI 辅助的代码执行、数据分析、可视化等。

特性

• 双向通信: 通过基于 WebSocket 的服务器将 Claude AI 连接到 Jupyter Notebook
• 单元格操作: 插入、执行和管理 notebook 单元格
• Notebook 管理: 保存 notebook 并检索 notebook 信息
• 单元格执行: 运行特定单元格或执行 notebook 中的所有单元格
• 输出检索: 获取已执行单元格的输出内容，并提供文本限制选项

组件

该系统由三个主要组件组成：

1. WebSocket 服务器 (jupyter_ws_server.py): 在 Jupyter 内部设置一个 WebSocket 服务器，用于桥接 notebook 和外部客户端之间的通信
2. 客户端 JavaScript (client.js): 在 notebook 中运行，处理操作（插入单元格、执行代码等）
3. MCP 服务器 (jupyter_mcp_server.py): 实现模型上下文协议并连接到 WebSocket 服务器

安装

前提条件

• Python 3.12 或更高版本 (可能也适用于旧版本，但未经测试)
• uv 包管理器
• Claude AI 桌面应用程序

安装 uv

如果您使用的是 Mac：

brew install uv

在 Windows 上 (PowerShell)：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

对于其他平台，请参阅 uv 安装指南。

设置

1. 克隆或下载此存储库到您的计算机：

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

2. 使用所需的包创建虚拟环境，并安装 jupyter-mcp 内核，以便您的 jupyter 安装（如果之前有）可以识别它。

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

3. (可选) 安装用于分析的其他 Python 包：

   uv pip install seaborn
   

4. 配置 Claude 桌面集成： 转到 Claude > Settings > Developer > Edit Config > claude_desktop_config.json 以包含以下内容：

      {
       "mcpServers": {
           "jupyter": {
               "command": "uv",
               "args": [
                   "--directory",
                   "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/src",
                   "run",
                   "jupyter_mcp_server.py"
               ]
           }
       }
   }
   

   将 /ABSOLUTE/PATH/TO/ 替换为系统上 src 文件夹的实际路径。例如：

   • Windows: "C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"
   • Mac: /Users/MyUser/GitHub/jupyter-notebook-mcp/src/

   如果您之前打开过 Claude，请 File > Exit 并重新打开它。

用法

启动连接

1. 启动您的 Jupyter Notebook (version 6.x) 服务器：

   uv run jupyter nbclassic
   

2. 创建一个新的 Jupyter Notebook，并确保选择 jupyter-mcp 内核：kernel -> change kernel -> jupyter-mcp

3. 在 notebook 单元格中，运行以下代码以初始化 WebSocket 服务器：

   import sys
   sys.path.append('/path/to/jupyter-notebook-mcp/src')  # 添加脚本所在的路径
   
   from jupyter_ws_server import setup_jupyter_mcp_integration
   
   # 在 Jupyter 内部启动 WebSocket 服务器
   server, port = setup_jupyter_mcp_integration()
   

   不要忘记在此处将 '/path/to/jupyter-notebook-mcp/src' 替换为系统上的 src 文件夹。例如：

   • Windows: "C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\"
   • Mac: /Users/MyUser/GitHub/jupyter-notebook-mcp/src/

   

4. 启动启用 MCP 的 Claude 桌面应用程序。

与 Claude 一起使用

连接后，Claude 将有权访问以下工具：

• ping - 检查服务器连接
• insert_and_execute_cell - 在指定位置插入一个单元格并执行它
• save_notebook - 保存当前的 Jupyter notebook
• get_cells_info - 获取有关 notebook 中所有单元格的信息
• get_notebook_info - 获取有关当前 notebook 的信息
• run_cell - 按索引运行特定单元格
• run_all_cells - 运行 notebook 中的所有单元格
• get_cell_text_output - 获取特定单元格的文本输出内容
• get_image_output - 获取特定单元格的图像输出
• edit_cell_content - 编辑现有单元格的内容
• set_slideshow_type- 设置单元格的幻灯片放映类型