ChengJiale150/jupyter-mcp-server

📖 目录

• 项目简介
• 工具一览
• 快速上手
• 最佳实践
• 贡献指南
• 致谢

🎯 项目简介

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管理模块

Cell基本功能模块

Cell高级集成功能模块

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

🛠️ 快速上手

环境准备

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

安装Jupyter MCP Server

{
    "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

uv run fastmcp run src/main.py

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

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

使用Jupyter MCP Server

conda activate your_environment_name

cd your/path/to/your/project

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

jupyter lab

jupyter server list

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

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

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项目做出贡献，请：

1. Fork 本仓库
2. 创建您的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

贡献类型

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

开发帮助文档

• 可以详见项目架构文档辅助理解项目架构与关键通信流程

🤗 致谢

本项目受到以下项目的帮助,在此表示感谢:

• DataLayer: 感谢DataLayer开源的jupyter_nbmodel_client与jupyter_kernel_client库,为Jupyter MCP的快速开发提供了极大的帮助
• FastMCP: 感谢FastMCP的开发者们,没有FastMCP就没有Jupyter MCP的快速集成

此外,本项目还参考了以下已有Jupyter MCP服务的实现,在此也一并表示感谢:

• datalayer/jupyter-mcp-server
• jjsantos01/jupyter-notebook-mcp
• ihrpr/mcp-server-jupyter
• itisaevalex/jupyter-mcp-extended