JupyterMCP - Jupyter Notebook Model Context Protocol Integration

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

JupyterMCP 通过模型上下文协议（MCP）将 Jupyter Notebook 接入 Claude AI，使 Claude 能够直接与 Jupyter Notebook 交互并对其进行控制。此集成支持 AI 辅助代码执行、数据分析、可视化等功能。

⚠️ 兼容性警告

此工具仅兼容 Jupyter Notebook 6.x 版本。

它不适用于：

• Jupyter Lab
• Jupyter Notebook v7.x
• VS Code Notebooks
• Google Colab
• 任何其他 Notebook 界面

功能

• 双向通信：通过基于 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（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')  # Add the path to where the scripts are located
   
   from jupyter_ws_server import setup_jupyter_mcp_integration
   
   # Start the WebSocket server inside Jupyter
   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- 设置单元格的幻灯片类型

⚠️ 免责声明

这是一个实验性项目，请谨慎使用。此工具会在你的计算机上运行任意 Python 代码，如果使用不当，可能会修改或删除数据。请务必备份重要项目和数据。

示例提示词

让 Claude 执行 Notebook 操作：

Python 示例

你可以查看示例 Notebook和视频演示

You have access to a Jupyter Notebook server.

I need to create a presentation about Python's Seaborn library.  
The content is as follows:

- What is Seaborn?
- Long vs. Wide data format
- Advantages of Seaborn over Matplotlib
- Commonly used Seaborn functions
- Live demonstration (comparison of Seaborn vs. Matplotlib)
  - Bar plot
  - Line plot
  - Scatter plot

For each concept, I want the main explanations provided in markdown cells, followed by one or more Python code cells demonstrating its usage. Keep the text concise—the cells shouldn't exceed 10 lines each.

Use appropriate slideshow types for each cell to make the presentation visually appealing.

点击此处查看完整对话

Stata 示例

此示例需要使用 Stata 软件（v17 或更高版本），该软件不是开源的。如果你已经安装 Stata，则需要安装 stata-setup 包：

uv pip install stata-setup

然后，在 Notebook 的开头还需要添加：

import stata_setup
stata_setup.config('your_stata_installation_directory', 'your_stata_edition')

你可以查看示例 Notebook和视频演示

此练习来自John Robert Warren 教授的网页

You have access to a Jupyter Notebook server. By default it runs Python, but you can run Stata (v18) code in this server using the %%stata magic, for example:

%%stata
display "hello world"

Run the available tools to solve the exercise, execute the code, and interpret the results.

**EXERCISE:**

In this exercise, you will use data from the American Community Survey (ACS). The ACS is a product of the U.S. Census Bureau and involves interviewing millions of Americans each year. For an introduction to the ACS, visit the ACS website (here).

For this exercise, I have created a data file containing two variables collected from respondents of the 2010 ACS who lived in one of two metropolitan areas: Minneapolis/St Paul and Duluth/Superior. The two variables are: (1) People's poverty status and (2) the time it takes people to commute to work.

Use STATA syntax files you already have (from the first assignment or class examples) and modify them to accomplish the following goals.

1. Read the data file (`"./stata_assignment_2.dat"`) for this assignment into STATA.
2. Be sure to declare "zero" as a missing value for `TRANTIME`, the commuting time variable.
3. Create a new dichotomous poverty variable that equals "1" if a person's income-to-poverty-line ratio (`POVRATIO`) is less than 100, and "0" otherwise; see the bottom of the assignment for an example of how to do this in STATA.
4. Separately for Minneapolis/St Paul and Duluth/Superior, produce:
   - a histogram of the commuting time (`TRANTIME`) variable.
   - measures of central tendency and spread for commuting time.
   - a frequency distribution for the poverty status (0 vs 1) variable.
5. Separately for Minneapolis/St Paul and Duluth/Superior, use STATA code to produce:
   - a 95% confidence interval for the mean commuting time.
   - a 95% confidence interval for the proportion of people who are poor. See below for an example of how to do this in STATA.

Use the results from step #4 above to:

6. Separately for Minneapolis/St Paul and Duluth/Superior, manually calculate:
   - a 95% confidence interval for the mean commuting time.
   - a 95% confidence interval for the proportion of people who are poor.
7. Confirm that your answers from steps #5 and #6 match.

Based on the results above, answer this question:

8. How do you interpret the confidence intervals calculated in steps #5 and #6 above?

9. Finally, create a do file (.do) with the all the Stata code and the answers as comments.

---

**DESCRIPTION OF VARIABLES IN "STATA ASSIGNMENT 2.DAT"**

**METAREAD** (Column 4-7)  
Metropolitan Area  
- `2240`: Duluth-Superior, MN/WI  
- `5120`: Minneapolis-St. Paul, MN  

**POVRATIO** (Column 18-20)  
Ratio of person's income to the poverty threshold:  
- `<100`: Below Poverty Line  
- `100`: At Poverty Line  
- `>100`: Above Poverty Line  

**TRANTIME** (Column 21-23)  
Travel time to work  
- `0`: Zero minutes  
- `1`: 1 Minute  
- etc.

点击此处查看完整对话

使用外部客户端进行测试

你可以使用随附的外部客户端测试功能，无需使用 Claude Desktop：

uv run python src/jupyter_ws_external_client.py

这将显示一个交互式菜单，用于测试部分可用功能。

自动测试所有命令：

uv run python src/jupyter_ws_external_client.py --batch

故障排除

• 连接问题：如果遇到连接超时，客户端内置了重新连接机制。你也可以尝试重启 WebSocket 服务。
• 单元格执行问题：如果单元格无法执行，请检查单元格内容是否为有效的 Python/Markdown，以及 Notebook 内核是否正在运行。
• WebSocket 端口冲突：如果默认端口（8765）已被占用，服务将自动尝试查找可用端口。

限制

• 仅支持 Jupyter Notebook 6.x
• 单元格文本输出默认限制为 1500 个字符
• 不支持高级 Jupyter 小部件交互
• 连接可能会在一段时间不活动后超时

许可证

MIT

其他 Jupyter MCP

本项目受到以下类似 Jupyter MCP 集成的启发：

• ihrpr
• Datalayer