Jupyter Mcp Server

Name: Jupyter Mcp Server
Author: ChengJiale150

本地服务

github.com/ChengJiale150数据与分析952 周前更新

代码仓库

关于 Jupyter Mcp Server

Jupyter Mcp Server 是面向支持 MCP 的 IDE 与命令行工具的 Jupyter Notebook 管理服务，适用于数据分析与机器学习工作。它支持同时操作多个 Notebook、交互式执行，并返回文本、图片和表格等结果。

主要功能

01连接和管理多个 Notebook
02管理及编辑 Cell
03交互式执行 Cell
04读取文本、图片和表格输出
05执行不保存的临时代码

适用场景

01跨多个 Notebook 执行数据分析
02查看和修改 Notebook 中的 Cell
03根据 Cell 输出调整分析步骤
04临时运行代码片段或调试变量

MCP 相关

该服务通过 MCP 向 IDE 和命令行客户端提供 Notebook、Kernel 管理及 Cell 操作工具，包括连接、读取、修改和执行。

#jupyter #mcp #notebook-management

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "jupyter-mcp-server-chengjiale150": {
      "command": "uvx",
      "args": [
        "better-jupyter-mcp-server"
      ]
    }
  }
}

启动命令uvx better-jupyter-mcp-server

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypibetter-jupyter-mcp-server1.1.0stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
mode	enum	否	`connect`：连接到现有笔记本；`create`：创建并连接到新笔记本（该笔记本不得已存在）；`reconnect`：重新连接到现有笔记本connect \| create \| reconnect
notebook_name	string	是	唯一标识符，用于在后续操作中引用此笔记本
notebook_path	string	是	相对于 Jupyter 服务根目录的笔记本文件路径（例如，'./analysis.ipynb'）
server_url	string	是	Jupyter 服务 URL（例如，http://localhost:8888）
token	string	是	Jupyter 身份验证令牌

详细介绍

来自项目 README

🪐 Jupyter MCP Server

专门为AI连接与管理Jupyter Notebook而开发的MCP服务

由 ChengJiale150 开发

English | 中文

🎯 项目简介

Jupyter MCP Server 是一个基于 Model Context Protocol (MCP) 的服务，为目前最先进的的AI IDE(如 Cursor) 与CLI工具(如Gemini CLI)提供连接与管理Jupyter Notebook的能力。使得AI能够操作Notebook，进行数据分析、可视化、机器学习等任务。

🤔 为什么需要Jupyter MCP Server

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

现有的提供操作Notebook的工具或MCP服务，要么仅能阅读与编辑Notebook，要么仅能操纵单个Notebook，难以满足同时操纵多个Notebook的复杂需求。此外，大多数工具也不支持多模态输出，无法充分利用目前最先进的多模态大模型（如Gemini 2.5）的强大图文理解能力。

Jupyter MCP Server 就是为了解决这个问题而开发的。它通过MCP协议，向AI提供了管理Jupyter Kernel与Notebook的工具，使其能够操纵多个Notebook进行交互式的任务执行，并输出多模态结果，助力数据科学家提高分析效率。

✨ 关键亮点

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

🔧 工具一览

Notebook管理模块

名称	描述	说明
connect_notebook	连接/创建指定路径的Notebook	因为需要启动Kernel,工具执行时间较长(10s~30s)
list_notebook	列出所有目前连接的Notebook	用于查看目前已经连接的Notebook,方便多Notebook任务执行
restart_notebook	重启指定名称的Notebook	清除所有导入包与变量
read_notebook	读取指定名称的Notebook的源内容(不包含输出)	用于查看Notebook的源内容,仅在明确要求时才使用

Cell基本功能模块

名称	描述	说明
list_cell	列出指定名称的Notebook的所有Cell的基本信息	用于定位Cell的索引与作用
read_cell	读取指定名称的Notebook指定索引的Cell内容	支持图像、表格、文本等多种输出
delete_cell	删除指定名称的Notebook指定索引的Cell
insert_cell	在指定名称的Notebook指定索引处上方/下方插入Cell
execute_cell	执行指定名称的Notebook指定索引的Cell	返回Cell的输出结果
overwrite_cell	覆盖指定名称的Notebook指定索引的Cell内容	用于修改Cell内容

Cell高级集成功能模块

名称	描述	说明
append_execute_code_cell	在Notebook末尾添加并执行Code Cell	insert+execute的组合为高频操作,将其组合减少工具的调用次数
execute_temporary_code	执行临时代码块(不存储到Notebook中)	用于进行魔法指令执行、代码片段调试、查看中间变量取值等临时操作

工具的具体内容详见工具文档

🛠️ 快速上手

环境准备

Python 3.12+(推荐使用Anaconda)
uv(安装详见安装指南)

安装Jupyter MCP Server

uvx 快速安装(推荐)

在安装uv后,直接配置MCP的JSON格式即可,示例如下:

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

具体客户端集成详见集成文档

源代码

克隆项目并安装依赖

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

(可选)配置config.toml

进入src/config.toml文件,根据需要配置参数(如是否允许返回图片数据)

启动Jupyter MCP Server

uv run fastmcp run src/main.py

如果成功启动,会输出类似如下信息代表启动成功:

[09/14/25 20:14:59] INFO     Starting MCP server 'Jupyter-MCP-Server' with transport 'stdio'

配置标准JSON格式

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

具体客户端集成详见集成文档

使用Jupyter MCP Server

本地手动启动Jupyter Server

在正式使用前,需要连接Jupyter Server,这里介绍如何在本地手动启动Jupyter Server:

打开终端并激活环境:

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

对于使用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 Server:

使用下述命令启动Jupyter Server

jupyter lab

成功启动后会弹出浏览器窗口,你可以在此查看根路径是否为工程目录

获取认证Token:

使用下述命令获取认证Token

jupyter server list

运行后会输出类似如下信息:

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

其中YOUR_TOKEN为认证Token

添加提示词与规则

在正式使用前,你必须添加如下提示词于规则文件中以提供Jupyter MCP Server的必要连接信息:

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

此外,推荐在提示词中添加关键Notebook路径信息,方便AI快速定位目标Notebook提高connect_notebook工具的执行效率,可以在Jupyter Lab网页中右键点击目标Notebook文件,选择Copy Path获取相对路径

在提供上述内容后,你就可以开始使用Jupyter MCP Server了!

使用LLM托管Jupyter Server

安装必要依赖:

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

提供提示词与规则文档:

## Jupyter MCP Server 使用指南

在正式使用Jupyter MCP Server前,你**必须**完成如下步骤:

1. **启动Jupyter Server**:

在当前项目目录中以不阻塞当前终端的方式在命令行终端中输入启动Jupyter Server,例如:
- `Window`: `start jupyter lab`
- `MacOS/Linux`: `nohup jupyter lab &`

2. **获取URL与认证Token**:

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

仅当完成上述步骤后,你才可以使用Jupyter MCP Server

✅ 最佳实践

使用支持多模态输入的大模型(如Gemini 2.5 Pro)进行交互,以充分利用最先进的多模态理解能力
使用支持MCP协议返回图像数据并支持解析的客户端(如Cursor、Gemini CLI等),部分客户端可能不支持该功能
将复杂任务(如数据科学建模)拆分为多个子任务(如数据清洗、特征工程、模型训练、模型评估等),并逐步执行
给出结构清晰的提示词与规则,这里可以参考提示词与规则文档
在提示词中融入专家经验与智慧(如数据清洗、特征工程的技巧),这是AI最缺乏的,也是最需要补充的
尽可能提供丰富的上下文信息(如现有数据集的字段解释,文件路径,详细的任务要求等)
提供Few Shot案例,提供Baseline或已有Workflow作为参考

示例

Titanic数据集分析

🤝 贡献指南

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

Fork 本仓库
创建您的特性分支 (git checkout -b feature/AmazingFeature)
提交您的更改 (git commit -m 'Add some 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服务的实现,在此也一并表示感谢:

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

Made with ❤️ by ChengJiale150

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。