Jupyter Notebook MCP

JupyterMCP-Jupyter笔记本模型上下文协议集成

JupyterMCP连接 Jupyter笔记本 向 克劳德 AI 通过模型上下文协议（MCP），允许Claude直接与Jupyter笔记本交互和控制。这种集成实现了人工智能辅助的代码执行、数据分析、可视化等。

⚠️ 兼容性警告

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

它不适用于：

• Jupyter实验室
• Jupyter Notebook v7.x
• VS代码笔记本
• 谷歌Colab
• 任何其他笔记本电脑接口

特性

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

组件

该系统由三个主要部分组成：

1. WebSocket服务器(jupyter_ws_server.py)：在Jupyter中设置一个WebSocket服务器，连接笔记本电脑和外部客户端之间的通信
2. 客户端JavaScript(client.js)：在笔记本中运行以处理操作（插入单元格、执行代码等）
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"

有关其他平台，请参阅 紫外线安装指南.

设置

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

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

1. 使用安装所需的软件包创建虚拟环境 jupyter-mcp 内核，这样它就可以被您的jupyter安装识别出来，如果您以前有过的话。

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

1. （可选）为您的分析安装其他Python包：

   uv pip install seaborn

1. 配置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 系统上的文件夹。例如：

- 窗户： "C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\" - 雨衣： /Users/MyUser/GitHub/jupyter-notebook-mcp/src/

如果你之前打开过克劳德，那么 File > Exit 然后再打开它。

用法

启动连接

1. 启动Jupyter Notebook（版本6.x）服务器：

   uv run jupyter nbclassic

1. 创建一个新的Jupyter记事本，并确保您选择了 jupyter-mcp 内核： kernel -> change kernel -> jupyter-mcp

1. 在笔记本单元中，运行以下代码以初始化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 系统上的文件夹。例如：

- 窗户： "C:\\Users\\MyUser\\GitHub\\jupyter-notebook-mcp\\src\\" - 雨衣： /Users/MyUser/GitHub/jupyter-notebook-mcp/src/

Notebook setup

1. 启动启用MCP的Claude桌面。

与克劳德一起使用

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

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

⚠️ 免责声明

这是一个实验项目，应该谨慎使用。此工具在您的计算机中运行任意Python代码，如果不小心使用，可能会修改或删除数据。始终备份您的重要项目和数据。

示例提示

让克劳德执行笔记本操作：

Python示例

您可以查看 示例笔记本 和那个 视频演示

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示例

对于这个例子，你需要 国家 软件 （v17或更高版本），它不是开源的。如果您已经拥有Stata，则需要安装 stata-setup 包裹：

uv pip install stata-setup

然后，在笔记本的开头，你需要额外包括：

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

您可以查看 示例笔记本 和那个 视频演示

这个练习来自 约翰·罗伯特·沃伦教授网页

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`: 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，以及笔记本内核是否正在运行。
• WebSocket端口冲突：如果默认端口（8765）已在使用中，服务器将自动尝试查找可用端口。

局限性

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

许可证

麻省理工学院

其他Jupyter MCP

该项目的灵感来自Jupyter的类似MCP集成，如：

• ihrpr
• 数据层