Jupyter MCP Server

🚀 Jupyter_MCP_Server

JupyterMCP 实现了 Jupyter Notebook 与 Claude AI 通过 Model Context Protocol (MCP) 的集成。借助该集成，Claude 能够与 Jupyter 笔记本直接交互并进行控制，实现 AI 辅助的代码执行、数据分析、可视化等功能。

🚀 快速开始

启动连接

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

uv run jupyter notebook

2. 打开浏览器访问 http://localhost:8888，然后导航到 jupyter_mcp_server.py 笔记本。
3. 在笔记本中执行以下代码以启动 MCP 服务器：

from jupyter_mcp_server import start_server
start_server()

✨ 主要特性

• 双向通信：通过基于 WebSocket 的服务器将 Claude AI 连接到 Jupyter Notebook。
• 单元格操作：可插入、执行和管理笔记本中的单元格。
• 笔记本管理：支持保存笔记本并获取笔记本信息。
• 单元格执行：能执行特定的单元格或运行整个笔记本的所有单元格。
• 输出获取：可获取已执行单元格的输出内容，且带有文本限制选项。

📦 安装指南

先决条件

• Python 3.12 或更高版本（可能与旧版本兼容，但未测试）
• [uv 包管理器](/README.md#安装 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. 创建虚拟环境并安装所需的 packages，并安装 jupyter-mcp 内核，以便 Jupyter 安装程序识别：

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

3. （可选）安装数据分析的额外 Python 包：

uv pip install seaborn

4. 配置 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/，例如：

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

如果你之前已经打开了 Claude，请关闭并重新打开。

💻 使用示例

基础用法

在连接后，Claude 将具有访问以下工具的能力：

# 检查服务器连通性
ping

# 在指定位置插入单元格并执行它
insert_and_execute_cell

# 保存当前 Jupyter 笔记本
save_notebook

# 获取所有单元格的信息
get_cells_info

# 获取当前笔记本的信息
get_notebook_info

# 按照索引运行特定的单元格
run_cell

# 运行笔记本中的所有单元格
run_all_cells

# 获取特定单元格的输出内容
get_cell_text_output

# 获取特定单元格的图像输出
get_image_output

# 编辑现有单元格的内容
edit_cell_content

# 设置单元格的幻灯片类型
set_slideshow_type

🔧 技术细节

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

1. WebSocket 服务器 (jupyter_ws_server.py)：在 Jupyter 中设置一个 WebSocket 服务器，实现笔记本与外部客户端之间的桥梁通信。
2. 客户 JavaScript (client.js)：运行在笔记本中以处理操作（插入单元格、执行代码等）。
3. MCP 服务器 (jupyter_mcp_server.py)：实现 Model Context Protocol 并连接到 WebSocket 服务器。