Setup

To setup Jupyter MCP Server, you need to:

1. Set up your environment
2. Start JupyterLab
3. Configure your preferred MCP client.

Jupyter MCP Server supports both stdio and streamable HTTP transports.

Alternative: You can also use Smithery to install Jupyter MCP Server automatically for your preferred client.

Environment

Make sure you have the following packages installed in your environment. The collaboration package is needed as the modifications made on the notebook can be seen thanks to Jupyter Real Time Collaboration.

pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17

Start JupyterLab

Then, start JupyterLab with the following command.

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

You can also run make jupyterlab if you cloned the repository.

note

The --ip is set to 0.0.0.0 to allow the MCP server running in a Docker container to access your local JupyterLab.

Configuration

Stdio Transport

Use the following configuration file to set up the Jupyter MCP Server for your preferred MCP client. Note that the configuration is dependent on the operating system you are using.

important

Ensure the port of the SERVER_URLand TOKEN match those used in the jupyter lab command.

The NOTEBOOK_PATH should be relative to the directory where JupyterLab was started.

MacOS and Windows

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SERVER_URL",
        "-e",
        "TOKEN",
        "-e",
        "NOTEBOOK_PATH",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "SERVER_URL": "http://host.docker.internal:8888",
        "TOKEN": "MY_TOKEN",
        "NOTEBOOK_PATH": "notebook.ipynb"
      }
    }
  }
}

Linux

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SERVER_URL",
        "-e",
        "TOKEN",
        "-e",
        "NOTEBOOK_PATH",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "SERVER_URL": "http://localhost:8888",
        "TOKEN": "MY_TOKEN",
        "NOTEBOOK_PATH": "notebook.ipynb"
      }
    }
  }
}

Streamable HTTP Transport

Jupyter MCP Servers also supports streamable HTTP transport, which allows you to connect to the Jupyter MCP Server using a URL. To start the server, you can either use python or docker. The server will listen on port 4040, you can access it via http://localhost:4040.

Python

Clone the repository and use pip install -e . or just install the jupyter-mcp-server package from PyPI with pip install jupyter-mcp-server. Then, you can start the Jupyter MCP Server with the following command:

python -m jupyter-mcp-server --transport streamable_http

Docker

You can also run the Jupyter MCP Server using Docker. Use the following command to start the server:

docker run -p 4040:4040 datalayer/jupyter-mcp-server:latest --transport streamable-http

note

You can set the SERVER_URL (JupyterLab Server URL), TOKEN, and NOTEBOOK_PATH environment variables to configure the server with the -e option in the docker run command. If not set, the defaults will be used:

• SERVER_URL: http://host.docker.internal:8888
• TOKEN: MY_TOKEN
• NOTEBOOK_PATH: notebook.ipynb

Install via Smithery

To install Jupyter MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @datalayer/jupyter-mcp-server --client claude