datalayer/jupyter-mcp-server

🪐🔧 Jupyter MCP Server

What it is – An open‑source server that implements the Model Context Protocol (MCP) so AI agents (Claude, Cursor, VS Code extensions, etc.) can talk to a running Jupyter environment in real time. It sits between a Jupyter notebook (or JupyterHub, Datalayer‑hosted notebooks, Kaggle, Colab, etc.) and any MCP‑compatible client, exposing notebook files, cells, and kernel execution as structured tools that an LLM can call.

Why it matters – Modern AI assistants need live access to code, data, and visual output. By exposing notebooks through a stable protocol, the server lets agents:

• watch notebook changes instantly,
• run or edit cells programmatically,
• retrieve multimodal outputs (plots, images, tables), and
• keep work running on remote sandboxes (GPU‑backed clouds) even after the user disconnects.

Key capabilities

• Real‑time collaboration – changes in a notebook appear instantly to connected agents.
• Smart execution – cells are re‑run automatically when a previous run fails, using output feedback.
• Context‑aware tools – the server generates a live description of every operation (open notebook, list kernels, run cell, etc.) that MCP clients can discover automatically.
• Multimodal support – text, images, and plots are returned as structured data.
• Multiple sandbox back‑ends – run code on the local Jupyter server or on cloud sandboxes such as Datalayer, Kaggle, Google Colab, Modal, E2B, CoreWeave, Cloudflare, etc.
• OAuth 2.1 authentication – agents are redirected to a browser login; they receive scoped tokens (e.g., notebooks:read, code:execute) without ever seeing the user’s password.
• Observability – OpenTelemetry hooks let you trace tool calls and kernel executions.
• JupyterLab integration – when JupyterLab mode is enabled, native Lab commands become MCP tools.

Typical workflow

1. Start Jupyter (local, JupyterHub, or a hosted Datalayer notebook).
2. Run the Jupyter MCP Server (via uvx, Docker, or as a Jupyter Server extension).
3. Configure an MCP client – e.g., Claude Desktop, VS Code extension, or the cline CLI – with the server’s endpoint and authentication variables.
4. The client discovers the server’s tool list, then an LLM can issue commands like notebook_open, cell_insert, or execute_cell and receive the results instantly.

Getting started (quick)

# Install the server and a JupyterLab stack
pip install jupyterlab jupyter-collaboration jupyter-mcp-tools ipykernel

# Start JupyterLab (replace MY_TOKEN with a secret you keep)
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0

# Run the server with uvx (no Docker needed)
uvx jupyter-mcp-server@latest \
  --env JUPYTER_URL=http://localhost:8888 \
  --env JUPYTER_TOKEN=MY_TOKEN \
  --env ALLOW_IMG_OUTPUT=true

After that, point any MCP‑compatible client at http://localhost:8888 (or the hosted endpoint https://mcp.datalayer.run/mcp) and follow the browser‑based OAuth flow.

Installation options

• Python package – pip install jupyter-mcp-server (latest version on PyPI).
• Docker image – docker pull datalayer/jupyter-mcp-server (official image, pulls automatically).
• Hosted service – Datalayer offers a managed endpoint (https://mcp.datalayer.run/mcp) that requires no local process.

Supported sandbox variants (selected with SANDBOX_VARIANT and optional extra extras):

Variant	Install extra	Key env vars
jupyter-server (default)	–	JUPYTER_URL, JUPYTER_TOKEN
datalayer	jupyter-mcp-server[datalayer]	CODE_SANDBOX_URL, CODE_SANDBOX_TOKEN, SANDBOX_ENVIRONMENT
kaggle	jupyter-mcp-server[kaggle]	Kaggle credentials
google-colab	–	CODE_SANDBOX_URL, CODE_SANDBOX_ID, CODE_SANDBOX_PROXY_TOKEN
modal	jupyter-mcp-server[modal]	Modal API keys
… (e2b, coreweave, cloudflare, daytona, monty, etc.)	corresponding extras	respective API keys

License – BSD 3‑Clause (permissive, commercial‑friendly).

Who might use it

• AI‑assistant developers building agents that need to read/write notebooks, run code, and retrieve plots.
• Data scientists who want their LLMs to edit notebooks automatically while keeping a full audit trail.
• Platform providers (Datalayer, Kaggle, etc.) that want a standard way for third‑party AI tools to interact with hosted notebooks.
• Researchers exploring multimodal LLM workflows that combine code, data, and visual output.

Where to learn more

• Full docs: https://jupyter-mcp-server.datalayer.tech
• API reference (auto‑generated tool list): https://jupyter-mcp-server.datalayer.tech/mcp
• Community Discord: https://discord.gg/YQFwvmSSuR
• Source code & releases: https://github.com/datalayer/jupyter-mcp-server