Jupyter MCP Server for Windsurf: Setup & Config

What you can do with Jupyter in Windsurf

A live notebook interface combining precise cell edits, execution feedback, and multimodal results.

• Create, edit, and execute cells from an MCP assistant.
• Trace tool calls and kernel execution with observability hooks.

Before you start: Jupyter in Windsurf

• Python
• uv 0.6.14 or later
• A running authenticated Jupyter service
• JupyterLab collaboration setup as documented
• An MCP-compatible client

The environment setup includes ipykernel, pycrdt, and jupyter-mcp-tools, with JupyterLab pinned to 4.4.1 and jupyter-collaboration to 4.0.2. It separately warns that MCP_TOKEN is required from v1.0.0; consult its linked provider setup for that token's configuration. Image output needs compatible clients and models.

Jupyter Windsurf configuration

1. Choose Windsurf configuration scope

   For Jupyter MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Jupyter MCP Server to Windsurf

   Use the jupyter-mcp-server entry below in mcpServers. Keep Jupyter MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check Jupyter MCP Server in Windsurf

   Jupyter MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "jupyter-mcp-server": {
      "command": "uvx",
      "args": [
        "jupyter-mcp-server@latest"
      ],
      "env": {
        "JUPYTER_URL": "<URL of the running Jupyter service>",
        "JUPYTER_TOKEN": "<Jupyter authentication token>",
        "ALLOW_IMG_OUTPUT": "<true for image-capable clients, otherwise false>",
        "MCP_TOKEN": "<MCP authentication token required by the README's version 1.0.0 notice>"
      }
    }
  }
}

Jupyter tools available to Windsurf

Jupyter's stored tool list documents 19 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

list_files

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for list_files.

Enumerate directories and files exposed by the Jupyter service.

list_kernels

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for list_kernels.

Inspect available kernels and running kernel sessions.

connect_to_jupyter

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for connect_to_jupyter.

use_notebook

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for use_notebook.

list_notebooks

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for list_notebooks.

restart_notebook

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for restart_notebook.

unuse_notebook

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for unuse_notebook.

Disconnect a notebook and free its associated resources.

read_notebook

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for read_notebook.

Read notebook cell sources with brief or detailed output.

read_cell

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for read_cell.

Inspect one cell's source, metadata, and outputs.

insert_cell

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for insert_cell.

Add a code or Markdown cell at a chosen position.

delete_cell

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for delete_cell.

move_cell

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for move_cell.

overwrite_cell_source

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for overwrite_cell_source.

edit_cell_source

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for edit_cell_source.

execute_cell

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for execute_cell.

insert_execute_code_cell

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for insert_execute_code_cell.

Create a code cell and run it in one operation.

execute_code

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for execute_code.

Run code directly in the kernel, including magic and shell commands.

notebook_run-all-cells

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for notebook_run-all-cells.

Run current notebook cells in sequence when JupyterLab mode is enabled.

notebook_get-selected-cell

After refreshing Jupyter in Windsurf settings, check Cascade's tool list for notebook_get-selected-cell.

Inspect the selected notebook cell in JupyterLab mode.

Jupyter: full stored tool descriptions

Troubleshooting Jupyter in Windsurf

• Check uvx jupyter-mcp-server@latest (from uv, for Python tools) on the machine running Windsurf's MCP integration for Jupyter MCP Server; refresh MCP and inspect Cascade's tools.
• Check ALLOW_IMG_OUTPUT, JUPYTER_TOKEN, JUPYTER_URL, MCP_TOKEN for Jupyter MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Jupyter MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires a configured Jupyter environment and authentication tokens.
• Known limitation: Image handling depends on client and model capabilities.
• Known limitation: Dynamic server connection is unavailable in Jupyter extension mode.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions