📖 Documentation  ·  🔧 Tools  ·  💬 Community

No process to run. Datalayer now hosts this server for you at

`https://mcp.datalayer.run/mcp` — one endpoint for every agent and every notebook.

Sign in from your browser, approve what the agent may do, and your work keeps running

on the server after the agent disconnects.

→ **Hosted Jupyter MCP Server**

One command to connect Claude Code, with `/datalayer:notebook`, `/datalayer:run` and

`/datalayer:status` on top:

/plugin marketplace add datalayer/jupyter-mcp-server
/plugin install datalayer

→ **Datalayer plugin for Claude Code**

Free and open source, BSD 3-Clause — point it at any Jupyter you already run, local or

JupyterHub, no account needed.

Built and maintained by **Datalayer**, where the same server drives

always-on Notebooks with GPU Code Sandboxes and durable execution — so your agent keeps

working on your data when your laptop does not.

No token to copy and paste. An agent that meets this server unauthenticated is told

where to authenticate, opens your browser, and you sign in to Datalayer as yourself. The

agent never sees your password — it receives a token scoped to what you approved, and you

can disconnect one agent without touching the others.

What each agent may do is two separate decisions: the scopes you approve

(`notebooks:read`, `notebooks:write`, `code:execute`, `data:read`) say what kind of

operation it may perform, and your own Datalayer permissions still say which notebooks it

may touch. An agent can never reach a notebook you cannot.

Personal access tokens keep working, and remain the simpler path for a CLI or a script.

→ **OAuth and identity**

Pin `code-sandboxes` to match your `jupyter-mcp-server`. The sandbox variant

`jupyter` was renamed to `jupyter-server` in `code-sandboxes` 1.1.1, and the two packages

have to agree on the name.

Staying on an earlier jupyter-mcp-server

📦 Using uvx (Quick Start)

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

🐳 Using Docker (Production)

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

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

1. 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 (`CODE_SANDBOX_URL`).

1. Authentication: In most cases, document and code sandbox services use the same authentication token. Use `JUPYTER_TOKEN` for simplified config or set `DOCUMENT_TOKEN` and `CODE_SANDBOX_TOKEN` individually for different credentials.

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

1. 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 MCP Client Configuration.

🧩 Sandbox Variants

By default, code executes through the `code-sandboxes` `jupyter-server` variant against

a Jupyter Server (`SANDBOX_VARIANT=jupyter-server`). Setting `SANDBOX_VARIANT` to any

other value uses another code-sandboxes

engine via the sandbox's plain kernel client when the selected variant exposes

one, so the same notebook tools can run code on additional backends.

The spelling is not fussy: `google_colab`, `google-colab` and `GOOGLE-COLAB` all name the

same variant. The names below are the canonical ones.

Sandbox features are provided by the optional `jupyter_mcp_sandboxes` extension.

To expose sandbox lifecycle tools (`launch_sandbox`, `list_sandboxes`,

`use_sandbox`, `terminate_sandbox`) or run any non-`jupyter-server` sandbox variant,

install it with `pip install jupyter_mcp_sandboxes`.

Each engine has its own page with the credentials it needs, the accelerator options it

accepts and a worked client configuration — start from

**jupyter-mcp-server.datalayer.tech/code-sandboxes**.

🧪 Testing

Run the test suite:

pytest tests/

Required environment variables for tests:

• None for the default local suite.

Optional environment variables:

• `TEST_MCP_SERVER`: `true`/`false` toggle for standalone MCP server mode tests (default `true`).
• `TEST_JUPYTER_SERVER`: `true`/`false` toggle for Jupyter extension mode tests (default `true`).
• `DATALAYER_API_KEY`: required only for Datalayer cloud smoke/integration tests.
• `DATALAYER_RUN_URL`: optional custom Datalayer code sandbox URL for datalayer engine tests.
• `SANDBOX_ENVIRONMENT`: optional cloud environment override (for example `ai-agents-env`).

✅ 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!