📖 Table of Contents

• Key Features
• Tools Overview
• Getting Started
• Best Practices
• Contributing
• Resources

🚀 Key Features

• ⚡ 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.

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

🔧 Tools Overview

The server provides a rich set of tools for interacting with Jupyter notebooks, categorized as follows:

Server Management Tools

Multi-Notebook Management Tools

Cell Operations and Execution Tools

JupyterLab Integration

Available only when JupyterLab mode is enabled. It is enabled by default.

For more details on each tool, their parameters, and return values, please refer to the official Tools documentation.

🏁 Getting Started

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
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17

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, you should:

• 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.

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 uv. Ideal for local development and first-time users.
• 🐳 Using Docker (Recommended for Production): A containerized approach that ensures a consistent and isolated environment, perfect for production or complex setups.

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

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

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

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

✅ Best Practices

• Interact with LLMs that supports multimodal input (like Gemini 2.5 Pro) to fully utilize advanced multimodal understanding capabilities.
• Use a MCP client that supports returning image data and can parse it (like Cursor, Gemini CLI, etc.), as some clients may not support this feature.
• Break down complex task (like the whole data science workflow) into multiple sub-tasks (like data cleaning, feature engineering, model training, model evaluation, etc.) and execute them step-by-step.
• Provide clearly structured prompts and rules (👉 Visit our Prompt Templates to get started)
• Provide as much context as possible (like already installed packages, field explanations for existing datasets, current working directory, detailed task requirements, etc.).

🤝 Contributing

We welcome contributions of all kinds! Here are some examples:

• 🐛 Bug fixes
• 📝 Improvements to existing features
• ✨ New feature development
• 📚 Documentation improvements and prompt templates

For detailed instructions on how to get started with development and submit your contributions, please see our Contributing Guide.

Our Contributors

📚 Resources

Looking for blog posts, videos, or other materials about Jupyter MCP Server?

👉 Visit the Resources section in our documentation for more!