🪐 Jupyter MCP Server

An MCP service specifically developed for AI to connect and manage Jupyter Notebooks Developed by ChengJiale150 English | 中文 </div>

📖 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

| Name | Description | Notes | |:---:|:---:|:---:| | connect_notebook | Connect/create a Notebook at a specified path | Tool execution time is long (10s~30s) due to Kernel startup. | | list_notebook | List all currently connected Notebooks | Used to view currently connected Notebooks for multi-Notebook tasks. | | restart_notebook | Restart a specified Notebook | Clears all imported packages and variables. | | read_notebook | Read the source content (without output) of a connected Notebook | Used to view the source content of the Notebook, only used when the user explicitly instructs to read the full content of the Notebook. |

Basic Cell Function Module

| Name | Description | Notes | |:---:|:---:|:---:| | list_cell | List basic information of all cells in a specified Notebook | Used to locate cell index and purpose. | | read_cell | Read the content of a specific cell in a specified Notebook | Supports various outputs like images, tables, text, etc. | | delete_cell | Delete a specific cell in a specified Notebook | | | insert_cell | Insert a cell above/below a specific index in a specified Notebook | | | execute_cell | Execute a specific cell in a specified Notebook | Returns the output of the cell. | | overwrite_cell | Overwrite the content of a specific cell in a specified Notebook | Used to modify cell content. |

Advanced Integrated Cell Function Module

| Name | Description | Notes | |:---:|:---:|:---:| | append_execute_cell | Add and execute a cell at the end of a Notebook | A combination of insert+execute for frequent operations, reducing tool calls. | | execute_temporary_cell | Execute a temporary code block (not saved to the Notebook) | Used for magic commands, code snippet debugging, viewing intermediate variables, etc. | 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

<details> <summary>uvx Quick Installation (Recommended)</summary> After installing uv, configure the MCP JSON format directly, as shown below: ``json { "mcpServers":{ "Jupyter-MCP-Server":{ "command": "uvx", "args": [ "better-jupyter-mcp-server" ], "env": {}, "transport": "stdio" } } } ` For specific client integration, please see the Integration Documentation. </details> <details> <summary>Source Code</summary> 1. Clone the project and install dependencies `bash git clone https://github.com/ChengJiale150/jupyter-mcp-server cd jupyter-mcp-server uv sync ` 2. (Optional) Configure config.toml Go to the src/config.toml file and configure parameters as needed (e.g., whether to allow returning image data). 3. Start Jupyter MCP Server `bash uv run fastmcp run src/better_jupyter_mcp_server/server.py ` If it starts successfully, you will see output similar to this: `bash [09/14/25 20:14:59] INFO Starting MCP server 'Jupyter-MCP-Server' with transport 'stdio' ` 4. Configure Standard JSON Format `json { "mcpServers":{ "Jupyter-MCP-Server":{ "command": "uv", "args": [ "run", "--directory", "your/path/to/jupyter-mcp-server", "src/better_jupyter_mcp_server/server.py" ], "env": {}, "transport": "stdio" } } } ` For specific client integration, please see the Integration Documentation. </details>

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: `bash 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. `bash cd your/path/to/your/project ` 2. Install necessary dependencies: `bash 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. `bash 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 --- <div align="center"> If this project is helpful to you, please give us a ⭐️ Made with ❤️ by ChengJiale150 </div>