朱彼特-MCP服务器

Name: 朱彼特-MCP服务器
Author: ChengJiale150

作者：ChengJiale1507 星标更新：2025-11-01

项目介绍

<div align="center">

# 🪐 Jupyter MCP 服务器

<img title="封面" src="https://gips3.baidu.com/it/u=2612427752,866657108&fm=3081&app=3081&f=PNG?w=3024&h=1296" alt="Jupyter MCP 服务器" data-align="center" width="700">

<strong>专门为AI连接和管理Jupyter Notebook而设计的MCP服务</strong>

*由[ChengJiale150](https://github.com/ChengJiale150)开发*

[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Version](https://img.shields.io/pypi/v/better-jupyter-mcp-server.svg)](https://pypi.org/project/better-jupyter-mcp-server/)
[![mcp-registry](https://img.shields.io/badge/mcp--registry-v1.1.0-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.ChengJiale150/jupyter-mcp-server)

[English](https://github.com/ChengJiale150/jupyter-mcp-server/blob/main/README_EN.md) 中文

</div>

## 📖 目录

- [项目概述](#-%E9%A1%B9%E7%9B%AE%E7%AE%80%E4%BB%8B)
- [工具概述](#-%E5%B7%A5%E5%85%B7%E4%B8%80%E8%A7%88)
- [快速开始](#-%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89%8B)
- [最佳实践](#-%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5)
- [贡献指南](#-%E8%B4%A1%E7%8C%AE%E6%8C%87%E5%8D%97)
- [致谢](#-%E8%87%B4%E8%B0%A2)

## 🎯 项目概述

Jupyter MCP 服务器是一个基于[模型上下文协议（MCP）](https://modelcontextprotocol.io/)的服务平台，适用于目前最先进的AI集成开发环境（如[Cursor](https://www.cursor.com/)），以及命令行工具（如[Gemini CLI](https://github.com/google-gemini/gemini-cli)）。它提供了连接和管理Jupyter Notebook的能力，使AI能够操作Notebooks进行数据分析、可视化和机器学习等任务。

### 🤔 为什么需要一个Jupyter MCP服务器

Jupyter Notebook是数据科学家最常用的工具之一，提供了一个交互式环境，便于进行探索性任务，如数据分析、可视化和机器学习。然而，由于其固有的格式限制，AI很难像处理纯文本文件（如Markdown或Python文件）那样直接理解Notebook。

现有的用于操作Notebook的工具或MCP服务要么只能读取和编辑Notebook，要么只能操作单个Notebook，难以满足同时处理多个Notebook的复杂需求。此外，大多数工具不支持多模态输出，无法充分利用最新多模态大模型的强大图文理解能力（如Gemini 2.5）。

Jupyter MCP服务器就是为了应对这一问题而开发的。它通过MCP协议为AI提供了管理Jupyter内核和Notebook的工具，使其能够操作**多个Notebook**，执行**交互式**任务并输出**多模态**结果，从而帮助数据科学家提高分析效率。

### ✨ 关键亮点

- 🔌 **兼容MCP** 可在任何支持MCP协议的IDE或CLI工具中使用
- 📚 **多Notebook管理** 支持同时管理多个Notebook
- 🔁 **交互式执行** 能够根据单元格输出自动调整执行策略
- 📊 **多模态输出** 支持输出多模态结果，如文本、图像、表格等

## 🔧 工具概述

### Notebook管理模块

| 名称               | 描述           | 备注                                  |
|:----------------:|:------------------:|:-----------------------------------:|
| connect_notebook | 在指定路径连接/创建一个Notebook | 该工具执行时间较长（10秒~30秒），因为它需要启动内核。 |
| list_notebook    | 列出所有当前已连接的Notebook  | 用于查看当前已连接的Notebook，便于多Notebook任务执行 |
| restart_notebook | 重启指定名称的Notebook    | 清除所有导入的包和变量                          |
| read_notebook    | 读取指定名称的Notebook的源内容（不含输出） | 用于查看Notebook的源内容，仅在明确要求时使用 |

### 单元格的基本功能模块

| 名称           | 描述                       | 备注             |
|:------------:|:------------------------------:|:---------------:|
| list_cell    | 列出指定Notebook中所有单元格的基本信息    | 用于定位单元格的索引和目的  |
| read_cell    | 读取指定Notebook中具有特定名称和索引的单元格内容     | 支持各种输出，如图像、表格和文本 |
| delete_cell  | 删除指定名称的Notebook中指定索引的单元格 |                 |
| insert_cell  | 在指定名称的Notebook中指定索引上方/下方插入一个单元格 |                 |
| execute_cell | 执行指定名称的Notebook中指定索引的单元格 | 返回单元格的输出结果 |
| overwrite_cell | 覆盖指定名称和索引的Notebook中单元格的内容 | 用于修改单元格内容 |

### 单元格的高级集成功能模块

| 名称                     | 描述                     | 备注                                   |
|:----------------------:|:----------------------:|:------------------------------------:|
| append_execute_code_cell    | 在Notebook末尾添加并执行一个Code单元格   | 插入+执行组合是一个高频操作，减少此类组合的工具调用次数 |
| execute_temporary_code | 执行临时代码块（不存储在Notebook中） | 用于临时操作，如执行魔法命令、调试代码片段和查看中间变量值 |

关于工具的具体内容，请参阅[工具文档](https://github.com/ChengJiale150/jupyter-mcp-server/blob/main/docs/tools.md)

## 🛠️ 快速开始

### 环境准备

- Python 3.12+（推荐使用[Anaconda](https://www.anaconda.com/)）
- UV（安装详情请参考[安装指南](https://docs.astral.sh/uv/getting-started/installation/)）

### 安装Jupyter MCP服务器

<details>

<summary>uvx 快速安装（推荐）</summary>

安装UV后，直接配置JSON格式的MCP如下：

```json
{
    "mcpServers":{
        "Jupyter-MCP-Server":{
            "command": "uvx",
            "args": [
                "better-jupyter-mcp-server"
            ],
            "env": {
                "ALLOW_IMG": "true"
            },
            "transport": "stdio"
        }
    }
}

关于客户端具体集成细节，请参阅集成文档

</details> <details> <summary>源代码</summary>

克隆项目并安装依赖

git clone https://github.com/ChengJiale150/jupyter-mcp-server
cd jupyter-mcp-server
uv sync

（可选）配置config.toml

进入src/config.toml文件，根据需要配置参数（如是否允许返回图像数据）

启动Jupyter MCP服务器

uv run fastmcp run src/main.py

如果启动成功，会输出类似以下信息表示启动成功：

[09/14/25 20:14:59] INFO     启动MCP服务器'Jupyter-MCP-Server'，传输方式'stdio'

配置标准JSON格式

{
    "mcpServers":{
        "Jupyter-MCP-Server":{
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "your/path/to/jupyter-mcp-server",
                "src/main.py"
            ],
            "env": {},
            "transport": "stdio"
        }
    }
}

关于客户端具体集成细节，请参阅集成文档

</details>

使用Jupyter MCP服务器

<details> <summary>本地手动启动Jupyter服务器</summary>

正式使用前，需要连接到Jupyter服务器。这里是如何手动在本地启动Jupyter服务器：

打开终端并激活环境：

打开计算机终端命令行并激活环境

对于使用conda（Anaconda）的用户，可以使用以下命令激活环境：

conda activate your_environment_name

为了方便起见，可以直接使用base环境conda activate base）

然后切换到当前项目目录，以便于后续文件操作

cd your/path/to/your/project

安装必要的依赖：

pip uninstall -y pycrdt datalayer_pycrdt
pip install jupyter nbformat datalayer_pycrdt jupyter-collaboration

启动Jupyter服务器：

使用以下命令启动Jupyter服务器

jupyter lab

启动成功后，会弹出浏览器窗口，可以在其中检查根路径是否为项目目录

获取认证令牌：

使用以下命令获取认证令牌

jupyter server list

运行后会输出类似以下信息：

http://localhost:8888/?token=YOUR_TOKEN :: YOUR_PROJECT_PATH

其中YOUR_TOKEN是认证令牌

添加提示和规则

正式使用前，你必须在规则文件中添加以下提示，以提供Jupyter MCP服务器所需的必要连接信息：

以下是Jupyter服务器连接参数:
URL = http://localhost:8888
Token = YOUR_TOKEN

另外，建议在提示中包含关键Notebook路径信息，以帮助AI快速定位目标Notebook，提高connect_notebook工具的执行效率。可以通过右击Jupyter Lab网页中的目标Notebook文件并选择复制路径来获取相对路径。

提供以上内容后，就可以开始使用Jupyter MCP服务器了！

</details> <details> <summary>使用LLM托管Jupyter服务器</summary>

安装必要的依赖：

pip uninstall -y pycrdt datalayer_pycrdt
pip install jupyter nbformat datalayer_pycrdt jupyter-collaboration

提供提示词和规则文档：

## Jupyter MCP服务器使用指南

在正式使用Jupyter MCP服务器前，你**必须**完成以下步骤：

1. **启动Jupyter服务器**：

在当前项目目录中以不阻塞当前终端的方式在命令行终端中输入启动Jupyter服务器，例如：
- `Windows`：`start jupyter lab`
- `MacOS/Linux`：`nohup jupyter lab &`

2. **获取URL与认证令牌**：

使用`jupyter server list`获取URL与认证令牌

只有完成上述步骤后，你才能使用Jupyter MCP服务器

</details>

✅ 最佳实践

使用支持多模态输入的大模型（如Gemini 2.5 Pro）进行交互，充分利用最先进的多模态理解能力
使用支持通过MCP协议返回图像数据并解析的客户端（如Cursor、Gemini CLI等），因为某些客户端可能不支持此功能
将复杂的任务（如数据科学建模）分解成多个子任务（如数据清洗、特征工程、模型训练、模型评估等），并逐步执行
提供清晰且结构化的提示和规则，你可以参考提示和规则文档
在提示中融入专家经验和智慧（如数据清洗、特征工程技术），这是AI最缺乏且最需要补充的部分
提供尽可能多的上下文信息（如现有数据集字段解释、文件路径、详细的任务要求等）
提供Few Shot示例，并提供基线或现有工作流程作为参考

示例

泰坦尼克号数据集分析

🤝 贡献指南

我们欢迎社区贡献！如果您想为Jupyter MCP服务器项目做出贡献，请：

分叉这个仓库
创建您的功能分支git checkout -b feature/AmazingFeature
提交您的更改git commit -m '添加一些AmazingFeature'
推送到分支 (git push origin feature/AmazingFeature)
打开Pull Request

贡献类型

🐛 Bug修复
📝 旧功能增强
✨ 新功能开发
📚 文档改进
🌍 国际化支持

开发帮助文档

请参阅详细信息项目架构文档，以帮助理解项目架构和关键通信过程

🤗 致谢

本项目得到了以下项目的帮助，我们对此表示感谢：

DataLayer感谢DataLayer开源jupyter_nbmodel_client和jupyter_kernel_client库，极大地促进了Jupyter MCP的快速开发
FastMCP感谢FastMCP开发者，没有FastMCP就没有Jupyter MCP的快速集成

此外，本项目还借鉴了以下现有的Jupyter MCP服务实现，我们也对它们表示感谢：

如果这个项目对你有帮助，请给我们一个⭐️

由ChengJiale150制作 ❤️

</div> ```