Jupyter MCP Server

How to use

Connect your MCP client to the Jupyter MCP Server to start controlling notebooks. You can connect to a specific notebook, switch between multiple notebooks, or list available notebooks and kernels. Use the client’s prompts to read notebook content, insert or modify cells, execute code, and receive multimodal outputs such as images and plots.

How to install

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
```

```bash
# Start JupyterLab on port 8888, allowing access from any IP and setting a token
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0
```

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

MCP connection configurations

Two MCP connection methods are shown. Use the one that best fits your environment. Both options use the same environment variables to connect to your Jupyter instance.

Additional Docker-based setup (production)

{
  "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"
      }
    }
  }
}
```

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

Note: Ensure the notebook URL and token match your Jupyter deployment. The port used by JupyterLab should align with the URL you supply in JUPYTER_URL.

MCP overview

The server exposes a rich set of tools for interacting with Jupyter notebooks, including server management, multi-notebook control, cell operations, execution, and a JupyterLab integration mode for convenient UI interactions.

Best practices

Work with clients that can handle multimodal outputs and provide image data when needed. Break complex tasks into sub-tasks, such as data preparation, model work, and evaluation, to keep interactions clear and actionable. Provide well-structured prompts and share context like current workspace and notebook state to improve results.

Contributing

Contributions are welcome. You can suggest bug fixes, feature improvements, or new documentation. Follow established guidelines for submitting changes and ensure compatibility with MCP client integrations.

Resources

Explore additional resources for examples, tutorials, and community materials related to the Jupyter MCP Server to expand your integration and usage knowledge.

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.

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 content with brief or detailed format options.

read_cell

Read the 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, supporting magic and shell commands.

notebook_run-all-cells

Execute all cells in the current notebook sequentially.

jupyter-cite

Cite specific cells from a specified notebook via prompts.