🪐 Jupyter MCP Server

An MCP service specifically developed for AI to connect and manage Jupyter Notebooks

Developed by ChengJiale150

English | 中文

📖 Table of Contents

• Project Introduction
• Tools Overview
• Quick Start
• Best Practices
• Contribution Guidelines
• Acknowledgements

🎯 Project Introduction

Jupyter MCP Server is a service based on the Model Context Protocol (MCP), providing the most advanced AI IDEs (like Cursor) and CLI tools (like Gemini CLI) with the ability to connect and manage Jupyter Notebooks. This enables AI to operate Notebooks for tasks such as data analysis, visualization, and machine learning.

🤔 Why Jupyter MCP Server?

Jupyter Notebook is one of the most common tools for data scientists, offering an interactive environment for exploratory tasks like data analysis, visualization, and machine learning. However, due to the format limitations of Notebooks, they are not as easily understood by AI as plain text files (like Markdown or Python files).

Existing tools or MCP services for operating Notebooks either only support reading and editing or can only manipulate a single Notebook, making it difficult to meet the complex demands of managing multiple Notebooks simultaneously. Furthermore, most tools do not support multimodal output, failing to fully leverage the powerful image and text understanding capabilities of advanced multimodal large models (like Gemini 2.5).

Jupyter MCP Server was developed to address this issue. Through the MCP protocol, it provides AI with tools to manage Jupyter Kernels and Notebooks, enabling it to handle multiple Notebooks for interactive task execution and output multimodal results, helping data scientists improve their analysis efficiency.

✨ Key Highlights

• 🔌 MCP Compatible: Can be used in any IDE or CLI tool that supports the MCP protocol.
• 📚 Multi-Notebook Management: Supports managing multiple Notebooks at the same time.
• 🔁 Interactive Execution: Can automatically adjust execution strategies based on cell output.
• 📊 Multimodal Output: Supports outputting multimodal results, such as text, images, tables, etc.

🔧 Tools Overview

Notebook Management Module

Basic Cell Function Module

Advanced Integrated Cell Function Module

For more details on the tools, please see the Tools Documentation.

🛠️ Quick Start

Prerequisites

• Python 3.12+ (recommended to use Anaconda)
• uv (for installation, see the Installation Guide)

Installing Jupyter MCP Server

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

Starting Jupyter

Before formal use, you need to connect to a Jupyter Server. Here is how to start a Jupyter Server locally:

1. Open a terminal and activate the environment:

   Open your computer's terminal command line and activate the environment.

   For conda (Anaconda) users, you can use the following command to activate the environment:

   conda activate your_environment_name
   

   For convenience, you can use the base environment (conda activate base).

   Then switch to your current project directory for easier file operations.

   cd your/path/to/your/project
   

2. Install necessary dependencies:

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

3. Start Jupyter Server:

   Use the following command to start the Jupyter Server, where YOUR_TOKEN is the authentication token, which you can change.

   jupyter lab --port 8888 --IdentityProvider.token YOUR_TOKEN
   

   After a successful start, a browser window will pop up. You can check if the root path is your project directory.

Using Jupyter MCP Server

Before formal use, you must add the following prompt to your rules file to provide the necessary connection information for Jupyter MCP Server:

Here are the Jupyter server connection parameters:
URL = http://localhost:8888
Token = YOUR_TOKEN

Additionally, it is recommended to add key Notebook path information to the prompt to help the AI quickly locate the target Notebook and improve the execution efficiency of the connect_notebook tool. You can right-click the target Notebook file in Jupyter Lab and select Copy Path to get the relative path.

After providing the above content, you can start using Jupyter MCP Server!

✅ Best Practices

• Interact with a large model that supports multimodal input (like Gemini 2.5 Pro) to fully utilize advanced multimodal understanding capabilities.
• Use a client that supports returning image data via the MCP protocol and can parse it (like Cursor, Gemini CLI, etc.), as some clients may not support this feature.
• Break down complex tasks (like data science modeling) into multiple sub-tasks (like data cleaning, feature engineering, model training, model evaluation, etc.) and execute them step-by-step.
• Provide clearly structured prompts and rules. You can refer to the Prompt and Rules Documentation.
• Incorporate expert experience and wisdom (such as data cleaning and feature engineering techniques) into your prompts, as this is what AI lacks most and needs to be supplemented.
• Provide as much context as possible (such as field explanations for existing datasets, file paths, detailed task requirements, etc.).
• Provide Few Shot examples, provide Baseline or existing Workflow as a reference.

Examples

• Titanic Data Analysis

🤝 Contribution Guidelines

We welcome community contributions! If you would like to contribute to the Jupyter MCP Server project, please:

1. Fork this repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Types of Contributions

• 🐛 Bug fixes
• 📝 Improvements to existing features
• ✨ New feature development
• 📚 Documentation improvements
• 🌍 Internationalization support

Development Help Documentation

• You can refer to the Project Architecture Document to help understand the project architecture and key communication flows.

🤗 Acknowledgements

This project has been helped by the following projects, and we would like to express our gratitude:

• DataLayer: Thanks to DataLayer for open-sourcing the jupyter_nbmodel_client and jupyter_kernel_client libraries, which greatly helped the rapid development of Jupyter MCP.
• FastMCP: Thanks to the developers of FastMCP. Without FastMCP, the rapid integration of Jupyter MCP would not have been possible.

In addition, this project also referenced the implementations of the following existing Jupyter MCP services, and we would like to thank them as well:

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