🪐🔧 Jupyter MCP Server
An MCP server developed for AI to connect and manage Jupyter Notebooks in real-time
Developed by Datalayer
[!IMPORTANT] Breaking change in v1.0.0: You must configure
MCP_TOKENin your MCP client setup.For setup details, see: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-standalone/#3-configure-your-mcp-client
Update in v1.0.2:
pycrdtis now supported, so installingdatalayer_pycrdtis no longer required.
[!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
- ⚡ 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. |
move_cell |
Move a cell from one position to another within a notebook. |
overwrite_cell_source |
Overwrite the source code of an existing cell. |
edit_cell_source |
Apply surgical find-and-replace edits to a cell's source without full rewrite. |
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 pycrdt
[!TIP] To confirm your environment is correctly configured:
- Open a notebook in JupyterLab
- Type some content in any cell (code or markdown)
- Observe the tab indicator: you should see an "×" appear next to the notebook name, indicating unsaved changes
- Wait a few seconds—the "×" should automatically change to