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')  # 添加脚本所在的路径
   
   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- 设置单元格的幻灯片放映类型

⚠️ 免责声明

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

示例提示

要求 Claude 执行 notebook 操作：

Python 示例

您可以查看 示例 notebook 和 视频演示

您有权访问 Jupyter Notebook 服务器。

我需要创建一个关于 Python 的 Seaborn 库的演示文稿。
内容如下：

- 什么是 Seaborn？
- 长数据格式与宽数据格式
- Seaborn 相对于 Matplotlib 的优势
- 常用的 Seaborn 函数
- 现场演示（Seaborn 与 Matplotlib 的比较）
  - 条形图
  - 折线图
  - 散点图

对于每个概念，我希望在 markdown 单元格中提供主要解释，然后是一个或多个 Python 代码单元格来演示其用法。保持文本简洁——每个单元格不应超过 10 行。

为每个单元格使用适当的幻灯片放映类型，以使演示文稿在视觉上更具吸引力。

在此处查看完整对话

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 教授的网页

您有权访问 Jupyter Notebook 服务器。默认情况下，它运行 Python，但您可以使用 %%stata magic 在此服务器中运行 Stata (v18) 代码，例如：

%%stata
display "hello world"

运行可用的工具来解决练习，执行代码并解释结果。

**练习：**

在本练习中，您将使用来自美国社区调查 (ACS) 的数据。ACS 是美国人口普查局的产品，涉及每年对数百万美国人进行访谈。有关 ACS 的介绍，请访问 ACS 网站（此处）。

对于本练习，我创建了一个数据文件，其中包含从 2010 年 ACS 的受访者那里收集的两个变量，这些受访者居住在两个大都市区之一：明尼阿波利斯/圣保罗和德卢斯/苏必利尔。这两个变量是：(1) 人们的贫困状况和 (2) 人们上下班所需的时间。

使用您已有的 STATA 语法文件（来自第一个作业或课堂示例）并修改它们以实现以下目标。

1. 将此作业的数据文件（`"./stata_assignment_2.dat"`）读入 STATA。
2. 确保将 `TRANTIME`（通勤时间变量）的“零”声明为缺失值。
3. 创建一个新的二分贫困变量，如果一个人的收入与贫困线之比 (`POVRATIO`) 小于 100，则该变量等于“1”，否则等于“0”；有关如何在 STATA 中执行此操作的示例，请参见作业底部。
4. 分别针对明尼阿波利斯/圣保罗和德卢斯/苏必利尔，生成：
   - 通勤时间 (`TRANTIME`) 变量的直方图。
   - 通勤时间的集中趋势和离散程度的度量。
   - 贫困状况（0 与 1）变量的频率分布。
5. 分别针对明尼阿波利斯/圣保罗和德卢斯/苏必利尔，使用 STATA 代码生成：
   - 通勤时间平均值的 95% 置信区间。
   - 贫困人口比例的 95% 置信区间。有关如何在 STATA 中执行此操作的示例，请参见下文。

使用上面第 4 步的结果来：

6. 分别针对明尼阿波利斯/圣保罗和德卢斯/苏必利尔，手动计算：
   - 通勤时间平均值的 95% 置信区间。
   - 贫困人口比例的 95% 置信区间。
7. 确认您在第 5 步和第 6 步中的答案是否匹配。

根据以上结果，回答以下问题：

8. 您如何解释在上面第 5 步和第 6 步中计算的置信区间？

9. 最后，创建一个包含所有 Stata 代码和答案作为注释的 do 文件 (.do)。

---

**“STATA ASSIGNMENT 2.DAT”中变量的描述**

**METAREAD**（第 4-7 列）
大都市区
- `2240`: 德卢斯-苏必利尔，MN/WI
- `5120`: 明尼阿波利斯-圣保罗，MN

**POVRATIO**（第 18-20 列）
个人收入与贫困线的比率：
- `<100`: 低于贫困线
- `100`: 处于贫困线
- `>100`: 高于贫困线

**TRANTIME**（第 21-23 列）
上下班所需时间
- `0`: 零分钟
- `1`: 1 分钟
- 等等

在此处查看完整对话

使用外部客户端进行测试

您可以使用包含的外部客户端在不使用 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 widget 交互
• 连接可能会在不活动一段时间后超时

许可证

MIT

其他 Jupyter MCP

该项目受到 Jupyter 类似 MCP 集成的启发，例如：

• ihrpr
• Datalayer