Jupyter MCP Server

How to use

Connect with an MCP client to control notebooks, run code, and read outputs. You can switch between notebooks, read and edit cells, execute code, and receive rich multimodal results such as images and plots. The server supports both local (stdio) and remote (http) deployment methods, so you can run it directly on your machine or in a container. Use the client prompts to select a notebook, issue commands, and view results in real time.

How to install

Prerequisites: ensure you have Python and pip installed, and you can install optional tooling for MCP client connectivity. You will also install a small set of packages to enable Jupyter real-time collaboration.

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

Start a JupyterLab session on your host, configuring the port and token for MCP access.

jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

Choose your preferred MCP client connection method. You can use uvx for a quick start or Docker for production-grade isolation.

Additional configuration and setup

The MCP server can be connected through two main methods. The first uses a lightweight, local client (uvx). The second uses Docker to run the MCP server in a container. You provide the notebook server URL and authentication token via environment variables, and you can enable image outputs if your client supports multimodal results.

# uvx quick-start example already shown below in the configuration snippet

For local development or containerized production, you’ll configure the MCP server connection as shown in the following two examples. Adapt JUPYTER_URL and JUPYTER_TOKEN to your environment.

Best practices and tips

Use a MCP client that can handle image data and multimodal outputs to take full advantage of the server’s capabilities. Break complex tasks into smaller steps, and provide clear context to your assistant so it can operate across notebooks and cells efficiently.

Troubleshooting and notes

If you encounter authentication or connectivity issues, verify that the token you supply matches the token configured in JupyterLab and that the URL points to the correct notebook server. Ensure the port in your JUPYTER_URL matches the port you started JupyterLab with.

Examples of client configuration

Below are the two explicit connection methods shown for MCP clients. Use these exact configurations to connect your MCP client to the Jupyter MCP Server.

json
{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": ["jupyter-mcp-server@latest"],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

json
{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JUPYTER_URL",
        "-e", "JUPYTER_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://host.docker.internal:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

Prompt overview

The server also supports prompts for MCP, including a tool to cite specific cells from a notebook.

What you get with this server

Real-time notebook interaction, smart execution that adapts when runs fail, context-aware interactions, multimodal output support, and seamless multi-notebook management across Jupyter deployments.

list_files

List files and directories in the Jupyter server 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.

use_notebook

Connect to a notebook file, create a new one, or switch between notebooks.

list_notebooks

List all notebooks on the Jupyter server and their status.

restart_notebook

Restart the kernel for a specific managed notebook.

unuse_notebook

Disconnect from a notebook and release its resources.

read_notebook

Read notebook cells content with brief or detailed formats.

read_cell

Read full content of a single cell including metadata, source, and outputs.

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 and multimodal outputs.

insert_execute_code_cell

Insert a new code cell and execute it in one step.

execute_code

Execute code directly in the kernel, including magic and shell commands.

notebook_run-all-cells

Execute all cells in the current notebook sequentially.

notebook_get-selected-cell

Get information about the currently selected cell.

jupyter-cite

Cite specific cells from a notebook for prompt-based workflows.