Skip to main content

Clients

We have tested and validated the Jupyter MCP Server with the following clients:

The Jupyter MCP Server is also compatible with ANY MCP client — see the growing list in MCP clients. This means that you are NOT limited to the clients listed above.

Jupyter MCP Server supports both stdio and streamable HTTP transports.

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 DOCUMENT_URL and RUNTIME_URL match those used in the jupyter lab command.

  • The DOCUMENT_ID which is the path to the notebook you want to connect to, should be relative to the directory where JupyterLab was started.

  • In a basic setup, DOCUMENT_URL and RUNTIME_URL are the same. DOCUMENT_TOKEN, and RUNTIME_TOKEN are also the same.

  • More environment variables can be set, refer to the server configuration for more details. If not specified, the server will use the default values.

For MacOS and Windows​

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DOCUMENT_URL",
        "-e",
        "DOCUMENT_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "RUNTIME_URL",
        "-e",
        "RUNTIME_TOKEN",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "DOCUMENT_URL": "http://host.docker.internal:8888",
        "DOCUMENT_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "RUNTIME_URL": "http://host.docker.internal:8888",
        "RUNTIME_TOKEN": "MY_TOKEN"
      }
    }
  }
}

For Linux​

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

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.

Use the following configuration for you MCP client to connect to a running MCP Server.

{
  "mcpServers": {
    "jupyter": {
        "command": "npx",
        "args": ["mcp-remote", "http://127.0.0.1:4040/mcp"]
    }
  }
}