[!NOTE] We Need Your Feedback!

We're actively developing support for JupyterHub and Google Colab deployments. If you're using or planning to use Jupyter MCP Server with these platforms, we'd love to hear from you!

• 🏢 JupyterHub users: Share your deployment setup and requirements
• 🌐 Google Colab users: Help us understand your use cases and workflows

Join the conversation in our Community page - your feedback will help us prioritize features and ensure these integrations work seamlessly for your needs.

📖 Table of Contents

• Key Features
• MCP Overview
• Getting Started
• Best Practices
• Contributing
• Resources

🚀 Key Features

• ⚡ Real-time control: Instantly view notebook changes as they happen.
• 🔁 Smart execution: Automatically adjusts when a cell run fails thanks to cell output feedback.
• 🧠 Context-aware: Understands the entire notebook context for more relevant interactions.
• 📊 Multimodal support: Support different output types, including images, plots, and text.
• 📚 Multi-notebook support: Seamlessly switch between multiple notebooks.
• 🎨 JupyterLab integration: Enhanced UI integration like automatic notebook opening.
• 🤝 MCP-compatible: Works with any MCP client, such as Claude Desktop, Cursor, Windsurf, and more.
• 🔍 Observability: Built-in hook system with OpenTelemetry integration for tracing tool calls and kernel executions.

Compatible with any Jupyter deployment (local, JupyterHub, ...) and with Datalayer hosted Notebooks.

🔧 MCP Overview

🔧 Tools Overview

The server provides a rich set of tools for interacting with Jupyter notebooks, categorized as follows. For more details on each tool, their parameters, and return values, please refer to the official Tools documentation.

Server Management Tools

| Name | Description | | :--------------- | :----------------------------------------------------------------------------------------- | | list_files | List files and directories in the Jupyter server's file system. | | list_kernels | List all available and running kernel sessions on the Jupyter server. | | connect_to_jupyter | Connect to a Jupyter server dynamically without restarting the MCP server. Not available when running as Jupyter extension. Useful for switching servers dynamically or avoiding hardcoded configuration. Read more |

Multi-Notebook Management Tools

| Name | Description | | :----------------- | :--------------------------------------------------------------------------------------- | | use_notebook | Connect to a notebook file, create a new one, or switch between notebooks. | | list_notebooks | List all notebooks available on the Jupyter server and their status | | restart_notebook | Restart the kernel for a specific managed notebook. | | unuse_notebook | Disconnect from a specific notebook and release its resources. | | read_notebook | Read notebook cells source content with brief or detailed format options. |

Cell Operations and Execution Tools

| Name | Description | | :------------------------- | :------------------------------------------------------------------------------- | | read_cell | Read the full content (Metadata, Source and Outputs) of a single cell. | | insert_cell | Insert a new code or markdown cell at a specified position. | | delete_cell | Delete a cell at a specified index. | | overwrite_cell_source | Overwrite the source code of an existing cell. | | execute_cell | Execute a cell with timeout, supports multimodal output including images. | | insert_execute_code_cell | Insert a new code cell and execute it in one step. | | execute_code | Execute code directly in the kernel, supports magic commands and shell commands. |

JupyterLab Integration

Available only when JupyterLab mode is enabled. It is enabled by default.

When running in JupyterLab mode, Jupyter MCP Server integrates with jupyter-mcp-tools to expose additional JupyterLab commands as MCP tools. By default, the following tools are enabled:

| Name | Description | | :---------------------------- | :--------------------------------------------------------------------------------- | | notebook_run-all-cells | Execute all cells in the current notebook sequentially | | notebook_get-selected-cell | Get information about the currently selected cell |

You can now customize which tools from jupyter-mcp-tools are available using the allowed_jupyter_mcp_tools configuration parameter. This allows you to enable additional notebook operations, console commands, file management tools, and more.

# Example: Enable additional tools via command-line
jupyter lab --port 4040 --IdentityProvider.token MY_TOKEN --JupyterMCPServerExtensionApp.allowed_jupyter_mcp_tools="notebook_run-all-cells,notebook_get-selected-cell,notebook_append-execute,console_create"

For the complete list of available tools and detailed configuration instructions, please refer to the Additional Tools documentation.

📝 Prompt Overview

The server also supports prompt feature of MCP, providing a easy way for user to interact with Jupyter notebooks.

| Name | Description | | :------------- | :--------------------------------------------------------------------------------- | | jupyter-cite | Cite specific cells from specified notebook (like @ in Coding IDE or CLI) |

For more details on each prompt, their input parameters, and return content, please refer to the official Prompt documentation.

🏁 Getting Started

For comprehensive setup instructions—including Streamable HTTP transport, running as a Jupyter Server extension and advanced configuration—check out our documentation. Or, get started quickly with JupyterLab and STDIO transport here below.

1. Set Up Your Environment

pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17

[!TIP] To confirm your environment is correctly configured:

1. Open a notebook in JupyterLab
2. Type some content in any cell (code or markdown)
3. Observe the tab indicator: you should see an "×" appear next to the notebook name, indicating unsaved changes
4. Wait a few seconds—the "×" should automatically change to a "●" without manually saving

This automatic saving behavior confirms that the real-time collaboration features are working properly, which is essential for MCP server integration.

2. Start JupyterLab

# Start JupyterLab on port 8888, allowing access