MCP Directory

How to add Jupyter MCP Server to Windsurf

Connect AI to Jupyter Notebooks in real-time — run cells, read outputs, and manage multiple notebooks. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 1.2k★ · stdio · apikey · official

Windsurf config for Jupyter MCP Server

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

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Jupyter MCP Server config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Jupyter MCP Server's tools become available to Cascade.

Before you start

  • A running JupyterLab / Jupyter server (e.g. jupyterlab==4.4.1 with jupyter-collaboration, jupyter-mcp-tools, ipykernel, pycrdt)
  • uv / uvx (0.6.14+) for the quick-start method, or Docker for the production method
  • A Jupyter server token (JUPYTER_TOKEN) and, since v1.0.0, MCP_TOKEN configured in the MCP client

What Jupyter MCP Server can do in Windsurf

list_files

List files and directories in the Jupyter server's file system.

list_kernels

List all available and running kernel sessions on the Jupyter server.

connect_to_jupyter

Connect to a Jupyter server dynamically without restarting the MCP server. Not available when running as a Jupyter extension.

use_notebook

Connect to a notebook file, create a new one, or switch between notebooks.

list_notebooks

List all notebooks available on the Jupyter server and their status.

restart_notebook

Restart the kernel for a specific managed notebook.

unuse_notebook

Disconnect from a specific notebook and release its resources.

read_notebook

Read notebook cells source content with brief or detailed format options.

Security

Requires a Jupyter server token (JUPYTER_TOKEN) for authentication; as of v1.0.0 you must also configure MCP_TOKEN in your MCP client setup. The server connects to a running Jupyter/JupyterLab instance and can execute arbitrary code in its kernels, so treat the configured Jupyter endpoint and its token as sensitive.

Jupyter MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Jupyter MCP Server config there under the "mcpServers" key and restart the client.

Is Jupyter MCP Server safe to use with Windsurf?

Requires a Jupyter server token (JUPYTER_TOKEN) for authentication; as of v1.0.0 you must also configure MCP_TOKEN in your MCP client setup. The server connects to a running Jupyter/JupyterLab instance and can execute arbitrary code in its kernels, so treat the configured Jupyter endpoint and its token as sensitive.

Which transports are supported?

The quick-start uses STDIO transport with uvx (or Docker). The documentation also covers Streamable HTTP transport and running as a Jupyter Server extension.

Do I need to install datalayer_pycrdt?

No. As of v1.0.2, pycrdt is supported directly, so installing datalayer_pycrdt is no longer required.

What changed in v1.0.0?

v1.0.0 introduced a breaking change requiring you to configure MCP_TOKEN in your MCP client setup.

View repo Full Jupyter MCP Server page