Jupyter笔记本MCP

Name: Jupyter笔记本MCP
Author: jjsantos01

作者：jjsantos01112 星标更新：2025-04-02

安装使用来源：spider==github.com

项目介绍

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

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

⚠️ 兼容性警告

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

它不支持以下版本：

Jupyter Lab
Jupyter Notebook v7.x
VS Code 笔记本
Google Colab
其他任何笔记本界面

功能

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

组件

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

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

设置

将此仓库克隆或下载到你的计算机：

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

创建虚拟环境并安装所需的包，以及 jupyter-mcp 内核，以便它可以被你的 Jupyter 安装识别（如果之前已经安装过）。
```
uv run python -m ipykernel install --name jupyter-mcp
```
（可选）安装额外的 Python 包用于分析：
```
uv pip install seaborn
```
配置 Claude 桌面集成：前往 Claude > 设置 > 开发者 > 编辑配置 > 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，则需要 文件 > 退出 再重新打开。

使用方法

启动连接

启动你的 Jupyter Notebook（版本 6.x）服务器：
```
uv run jupyter nbclassic
```
创建一个新的 Jupyter Notebook，并确保选择 jupyter-mcp 内核：内核 -> 更改内核 -> jupyter-mcp
在笔记本单元格中运行以下代码以初始化 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/
启动启用 MCP 的 Claude 桌面应用。

使用 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 代码，如果不小心使用可能会修改或删除数据。始终备份重要的项目和数据。

示例提示

请求 Claude 执行笔记本操作：

Python 示例

你可以查看示例笔记本和视频演示

你有一个 Jupyter Notebook 服务器。

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

- 什么是 Seaborn？
- 长数据格式 vs. 宽数据格式
- Seaborn 相比 Matplotlib 的优势
- 常用的 Seaborn 函数
- 实时演示（Seaborn vs. Matplotlib 的比较）
  - 条形图
  - 折线图
  - 散点图

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

为每个单元格设置适当的幻灯片类型，使其演示更具视觉吸引力。

查看完整的对话

Stata 示例

对于这个示例，你需要 Stata 软件（v17 或更高版本），该软件不是开源的。如果你已经有 Stata，你需要安装 stata-setup 包：

uv pip install stata-setup

然后，在笔记本的开始部分，你需要额外包含：

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

你可以查看示例笔记本和视频演示

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

你有一个 Jupyter Notebook 服务器。默认情况下它运行 Python，但你可以使用 `%%stata` 魔法在该服务器上运行 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 vs 1）变量的频率分布。
5. 分别对明尼阿波利斯/圣保罗和杜鲁门/苏佩里奥，使用 STATA 代码生成：
   - 通勤时间的 95% 置信区间。
   - 贫困人口比例的 95% 置信区间。请参见下面如何在 STATA 中做到这一点的示例。

根据第 4 步的结果：

6. 分别对明尼阿波利斯/圣保罗和杜鲁门/苏佩里奥手动计算：
   - 通勤时间的 95% 置信区间。
   - 贫困人口比例的 95% 置信区间。
7. 确认步骤 5 和 6 的答案匹配。

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

8. 你如何解释步骤 5 和 6 中计算的置信区间？

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

---

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

**METAREAD** (第 4-7 列)  
大都市区  
- `2240`: Duluth-Superior, MN/WI  
- `5120`: Minneapolis-St. Paul, 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，并且笔记本内核正在运行。
WebSocket 端口冲突：如果默认端口（8765）已被占用，服务器会自动尝试找到一个可用的端口。

限制

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

许可证

MIT

其他 Jupyter MCP

此项目灵感来源于类似的 Jupyter MCP 集成，如：