jupyter-mcp-server

Supports Cursor, Windsurf, Mcp

• ⚡ Real-time control: Instantly view notebook changes as they happen.
• 🔁 Smart execution: Automatically adjusts when a cell run fails thanks to cell output feedback.
• 🧠 Context-aware: Understands the entire notebook context for more relevant interactions.
• 📊 Multimodal support: Support different output types, including images, plots, and text.
• 📚 Multi-notebook support: Seamlessly switch between multiple notebooks.
• 🎨 JupyterLab integration: Enhanced UI integration like automatic notebook opening.
• 🤝 MCP-compatible: Works with any MCP client, such as Claude Desktop, Cursor, Windsurf, and more.
• 🔍 Observability: Built-in hook system with OpenTelemetry integration for tracing tool calls and kernel executions.

Compatible with any Jupyter deployment (local, JupyterHub, ...) and with Datalayer hosted Notebooks.

For comprehensive setup instructions—including Streamable HTTP transport, running as a Jupyter Server extension and advanced configuration—check out our documentation. Or, get started quickly with JupyterLab and STDIO transport here below.

1. Set Up Your Environment

pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel pycrdt

[!TIP] To confirm your environment is correctly configured:

1. Open a notebook in JupyterLab
2. Type some content in any cell (code or markdown)
3. Observe the tab indicator: you should see an "×" appear next to the notebook name, indicating unsaved changes
4. Wait a few seconds—the "×" should automatically change to a "●" without manually saving

This automatic saving behavior confirms that the real-time collaboration features are working properly, which is essential for MCP server integration.

2. Start JupyterLab

# 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

[!NOTE] If you are running notebooks through JupyterHub instead of JupyterLab as above, refer to our JupyterHub setup guide.

3. Configure Your Preferred MCP Client

Next, configure your MCP client to connect to the server. We offer two primary methods—choose the one that best fits your needs:

• 📦 Using uvx (Recommended for Quick Start): A lightweight and fast method using . Ideal for local development and first-time users.

First, install uv:

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

See more details on uv installation.

Then, configure your client:

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

On macOS and Windows:

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

On Linux:

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

[!TIP]

1. Port Configuration: Ensure the port in your Jupyter URLs matches the one used in the jupyter lab command. For simplified config, set this in JUPYTER_URL.
2. Server Separation: Use JUPYTER_URL when both services are on the same server, or set individual variables for advanced deployments. The different URL variables exist because some deployments separate notebook storage (DOCUMENT_URL) from kernel execution (RUNTIME_URL).
3. Authentication: In most cases, document and runtime services use the same authentication token. Use JUPYTER_TOKEN for simplified config or set DOCUMENT_TOKEN and RUNTIME_TOKEN individually for different credentials.
4. Notebook Path: The DOCUMENT_ID parameter specifies the path to the notebook the MCP client default to connect. It should be relative to the directory where JupyterLab was started. If you omit DOCUMENT_ID, the MCP client can automatically list all available notebooks on the Jupyter server, allowing you to select one interactively via your prompts.
5. Image Output: Set ALLOW_IMG_OUTPUT to false if your LLM does not support mutimodel understanding.

For detailed instructions on configuring various MCP clients—including Claude Desktop, VS Code, Cursor, Cline, and Windsurf — see the Clients documentation.

1. Jupyter Server

The default engine. Point the server at a running Jupyter Server:

pip install jupyter-mcp-server

"env": {
  "JUPYTER_URL": "http://localhost:8888",
  "JUPYTER_TOKEN": "MY_TOKEN"
}

2. JupyterHub

JupyterHub uses the same jupyter engine, targeting a user's single-user server. Authenticate with a JupyterHub API token that has the access:servers scope:

"env": {
  "RUNTIME_URL": "https://your-jupyterhub.domain/user/<username>",
  "RUNTIME_TOKEN": "your-jupyterhub-api-token",
  "DOCUMENT_URL": "https://your-jupyterhub.domain/user/<username>",
  "DOCUMENT_TOKEN": "your-jupyterhub-api-token"
}

See the JupyterHub setup guide for full details.

3. Datalayer

Execute on the Datalayer cloud runtime with GPU support and persistence:

pip install "jupyter-mcp-server[datalayer]"

"env": {
  "SANDBOX_VARIANT": "datalayer",
  "RUNTIME_URL": "https://prod1.datalayer.run",
  "RUNTIME_TOKEN": "your-datalayer-token",
  "SANDBOX_ENVIRONMENT": "python-cpu-env"
}

4. Kaggle

Execute against Kaggle. By default, when no runtime URL/channels are provided, the server uses the transparent Kaggle batch path from code-sandboxes. If runtime values are provided, it uses Kaggle interactive kernel mode.

pip install "jupyter-mcp-server[kaggle]"

"env": {
  "SANDBOX_VARIANT": "kaggle",
  "KAGGLE_API_TOKEN": "...",
  "SANDBOX_GPU": "T4"
}

To force interactive runtime mode, provide RUNTIME_URL and either:

• KAGGLE_API_TOKEN / RUNTIME_TOKEN (create kernel), or
• RUNTIME_ID / RUNTIME_CHANNELS_URL (connect existing kernel).

Supported Kaggle accelerator values include: NvidiaTeslaP100, NvidiaTeslaT4, NvidiaTeslaT4Highmem, NvidiaL4, NvidiaL4X1, NvidiaTeslaA100, NvidiaH100, and NvidiaRtxPro6000. Aliases such as P100 and T4 are accepted.

Note: Kaggle free-tier availability usually includes P100 and T4. Other accelerators are commonly restricted to specific competitions or internal Kaggle workloads.

5. Google Colab

Execute against a Google Colab runtime. Install the extra and provide the values from an active Colab notebook session:

pip install "jupyter-mcp-server[colab]"

"env": {
  "SANDBOX_VARIANT": "colab",
  "RUNTIME_URL": "https://8080-m-s-kkb-...-d.us-east1-0.prod.colab.dev",
  "RUNTIME_ID": "a1b2c3d4-....",
  "RUNTIME_PROXY_TOKEN": "ya29...."
}

The proxy token (colab-runtime-proxy-token) is short-lived; refresh it when it expires.

You can also pass RUNTIME_CHANNELS_URL with the Colab channels WebSocket URL and let the server derive RUNTIME_URL and RUNTIME_ID.

6. Monty

Execute in Monty, a secure in-process Python interpreter — ideal for short, safe LLM snippets. No credentials required.

pip install "jupyter-mcp-server[monty]"

"env": {
  "SANDBOX_VARIANT": "monty"
}

Monty supports only a subset of Python; third-party libraries and rich display outputs are not available.

7. Modal

Execute in a Modal cloud sandbox. Install the extra and configure Modal credentials:

pip install "jupyter-mcp-server[modal]"
modal token new

For local development, modal token new is usually enough because the Modal SDK loads credentials from ~/.modal.toml.

If you run in CI/CD, containers, or hosted runners, set both environment variables below.

"env": {
  "SANDBOX_VARIANT": "modal",
  "MODAL_TOKEN_ID": "ak-...",
  "MODAL_TOKEN_SECRET": "as-..."
}

Why both variables? Modal uses a token pair for environment-based auth:

• MODAL_TOKEN_ID: public token identifier.
• MODAL_TOKEN_SECRET: secret half paired with that id.

Providing only one is insufficient for authentication.

If needed, export both values from your local Modal config:

python - <<'PY'
import pathlib
import tomllib

cfg = tomllib.loads(pathlib.Path("~/.modal.toml").expanduser().read_text())
profile = cfg.get("default", cfg)
token_id = profile.get("token_id")
token_secret = profile.get("token_secret")
if token_id and token_secret:
    print(f"export MODAL_TOKEN_ID={token_id}")
    print(f"export MODAL_TOKEN_SECRET={token_secret}")
else:
    raise SystemExit("Could not find token_id/token_secret in ~/.modal.toml")
PY

You can also select the engine on the command line with --sandbox-variant, --runtime-proxy-token, and --sandbox-environment.