Skip to main content

STDIO Transport

1. Start JupyterLab​

Environment setup​

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 jupyter-mcp-tools>=0.1.4 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17

JupyterLab start​

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.

info

For JupyterHub:

  • Set the environment variable JUPYTERHUB_ALLOW_TOKEN_IN_URL=1 in the single-user environment.
  • Ensure your API token (MY_TOKEN) is created with access:servers scope in the Hub.

2. Setup Jupyter MCP Server​

Choose your deployment method: uvx (lightweight, recommended for first try) or Docker (production-ready).

important

Before You Start:

  • Ensure the port in your configuration matches your jupyter lab command port
  • See the server configuration guide for all available options and detailed examples

Using UVX (Quick Start)​

First, install uv:

pip install uv
uv --version  # should be 0.6.14 or higher

Simplified Configuration (Recommended):

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

For deployments requiring separate document storage and runtime execution:

{
  "mcpServers": {
    "jupyter": {
      "command": "uvx",
      "args": ["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",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

Using Docker (Production)​

Configuration varies by operating system. For complete configuration options, see the server configuration guide.

For MacOS and Windows​

Simplified Configuration (Recommended):

{
  "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"
      }
    }
  }
}
Advanced Configuration (Optional)

For deployments requiring separate document storage and runtime execution:

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DOCUMENT_URL",
        "-e", "DOCUMENT_TOKEN",
        "-e", "DOCUMENT_ID",
        "-e", "RUNTIME_URL",
        "-e", "RUNTIME_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "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",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

For Linux​

Simplified Configuration (Recommended):

{
  "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"
      }
    }
  }
}
Advanced Configuration (Optional)

For deployments requiring separate document storage and runtime execution:

{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DOCUMENT_URL",
        "-e", "DOCUMENT_TOKEN",
        "-e", "DOCUMENT_ID",
        "-e", "RUNTIME_URL",
        "-e", "RUNTIME_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "--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",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

For advanced configurations with separate document storage and runtime execution, see the complete configuration examples.

Troubleshooting​

Common Issues​

Connection refused or invalid JSON:

  • Verify Jupyter server is running: curl http://localhost:8888
  • Check JUPYTER_TOKEN matches your server token
  • For Docker on macOS/Windows: Use http://host.docker.internal:8888
  • For Docker on Linux: Add --network=host flag

Authentication errors:

  • Test token: curl -H "Authorization: token YOUR_TOKEN" http://localhost:8888/api/sessions
  • Check token in Jupyter server logs or URL parameters

For detailed troubleshooting and advanced configuration, see the configuration guide.