Jupyter Notebook MCP Server

A VS Code / Cursor extension that exposes Jupyter notebook manipulation via MCP (Model Context Protocol): read/edit/run cells and capture outputs. Works with Claude Code, Cursor Agent, Windsurf, and any MCP-compatible AI assistant.

Install: VS Code Marketplace · GitHub

[!NOTE] This project is an independent fork of olavocarvalho/vscode-runtime-notebook-mcp, licensed under MIT. Fork additions include broker/worker multi-window routing, notebook_get_summary, cell_id-based operations, and stress/verify improvements.

[!IMPORTANT] This project is still pre-alpha so it's very rough on the edge. Working in multiple windows is unstable.

Why connect to VS Code Runtime API?

There are currently two main architectures to give AI agents access to Jupyter notebooks. This project was heavily inspired by both - kudos to these teams for pioneering the space:

Architecture 1: File-based (e.g., cursor-notebook-mcp)

These servers read/write .ipynb files directly using libraries like nbformat.

Pros: No server dependencies, works out-of-the-box

Cons:

• Cannot execute code - agents can only edit cells, user must run them manually
• UI sync issues - VS Code may show stale content until you revert/reopen
• The .ipynb JSON format is verbose (~3x more tokens than raw code)
• Race conditions if you edit while agent writes

Architecture 2: Jupyter Server API (e.g., jupyter-mcp-server)

These servers connect to Jupyter's REST API and can execute code through the kernel.

Pros: Can execute code, best choice for standalone remote JupyterLab/JupyterHub deployments

Cons:

• Requires running JupyterLab separately (jupyter lab --port 8888)
• Auth setup: tokens, URLs, environment variables
• You end up running two UIs: one for notebook and another for AI
• If you open the notebook in VS Code you create another source of truth (Jupyter server state vs your editor)

Architecture 3: VS Code / Cursor Runtime API (this extension)

We're introducing a third architecture - hooking directly into Cursor/VS Code's Notebook API, the same API the editor uses internally.

Pros:

• Zero config - just install, server starts automatically
• Faster reads (direct memory access, no serialization)
• Executes code in your existing kernel (the one VS Code already manages)
• Changes appear instantly in the editor with full undo/redo support
• Single source of truth: what you see is what the agent sees
• Works with remote kernels - if VS Code connects to a remote Jupyter server, so does the agent

Cons:

• Only works inside VS Code / Cursor (won't help if you use JupyterLab web UI)

When to use what

Features

• Execute code in the active kernel and retrieve outputs
• Full cell manipulation - insert, edit, delete, move cells
• Read cell contents and outputs including images (base64)
• Search and navigate - find text, get notebook outline
• Bulk operations - add multiple cells, clear all outputs

Tools (20)

Navigation & Reading

Cell Manipulation

Execution & Outputs

To execute ad-hoc code, use notebook_insert_cell with execute: true. To execute an existing cell, use notebook_run_cell.

{
  "content": "print('hello')",
  "type": "code",
  "index": 0,
  "language": "python",
  "execute": false
}

{
  "cell_id": "abc123cellid",
  "content": "# New content"
}

{
  "query": "import pandas",
  "case_sensitive": false,
  "context_lines": 1
}

{
  "from_index": 5,
  "to_index": 0
}

{
  "cells": [
    {"content": "# Header", "type": "markdown"},
    {"content": "x = 1", "type": "code", "language": "python"}
  ],
  "index": 0
}

{
  "cell_id": "abc123cellid"
}

Setup

1. Install the extension in VS Code or Cursor
2. Recommended (low-permission) MCP client config via stdio proxy:

{
  "mcpServers": {
    "notebook": {
      "command": "node",
      "args": [
        "/ABS/PATH/vscode-runtime-notebook-mcp/scripts/mcp-stdio-proxy.mjs"
      ],
      "env": {
        "MCP_BASE_URL": "http://127.0.0.1:49777/mcp"
      }
    }
  }
}

3. HTTP config (alternative):

{
  "mcpServers": {
    "notebook": {
      "url": "http://127.0.0.1:49777/mcp"
    }
  }
}

[!ATTENTION] The server starts automatically when VS Code / Cursor opens. Look for the 🪐 :<port> indicator in the status bar.

Multi-window mode now uses a fixed endpoint model:

• One window becomes the broker on notebook-mcp.port (default 49777).
• Other windows start local workers on 49778+ and auto-register to the broker.
• MCP clients can keep a single config URL (http://127.0.0.1:49777/mcp).

stdio mode is recommended for sandboxed agents to reduce repeated localhost/network permission prompts.

Configuration

Verification Scripts

For repeatable validation in development:

npm run gen_notebooks   # Generate deterministic test notebooks
npm run bootstrap       # Check health + MCP initialize/tools/list
npm run self_check      # MCP-only health/workers/active-notebooks check (no curl/lsof/ps)
npm run smoke           # initialize -> tools/list -> list_open (+ requires kernel in verify)
npm run api_stability   # Exercise notebook tools, requiring 3 notebooks / 3 kernels in verify
npm run stress          # 3-notebook triad stress (reader/editor/executor lanes in parallel)
npm run stress:nightly  # Strict nightly triad profile on 3 distinct runtime kernels (>=1 run-capable lane)
npm run stress:nightly:x2 # Run strict nightly profile twice (quick pre-release confidence)
npm run verify:strict:5 # Strict 5-notebook full gate (requires 5 open notebooks with 5 kernels)
npm run stress:soak:5   # Heavier 5-notebook soak profile
npm run verify          # bootstrap -> smoke(kernel required) -> api_stability(strict) -> stress(strict)

Permission-Minimal Workflow (P0)

• Prefer stdio MCP config (scripts/mcp-stdio-proxy.mjs) over direct HTTP from sandboxed agents.
• Use npm run self_check for health/workers/notebook inventory instead of ad-hoc curl/ps/lsof.
• Keep automation on stable npm scripts (verify, verify:strict:5, stress:nightly:x2) to reuse command-prefix approvals.
• Keep test scripts writing inside workspace paths only.

Performance

Tested with a 471-cell notebook (~2.8MB, 1MB outputs):

[!NOTE] Read operations are sub-millisecond because they access in-memory data structures directly. Write operations (~7ms) go through VS Code's edit pipeline for undo/redo support.

Requirements

• VS Code 1.85+ or Cursor 0.43+
• Jupyter extension

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         VS Code / Cursor                                │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                    Jupyter Extension                              │  │
│  │                                                                   │  │
│  │   Notebook Document  ◄───►  Kernel (Python)  ───►  Outputs        │  │
│  │                                    ▲                              │  │
│  └────────────────────────────────────┼──────────────────────────────┘  │
│                                       │                                 │
│  ┌────────────────────────────────────┼──────────────────────────────┐  │
│  │              Notebook MCP Server Extension                        │  │
│  │                                    │                              │  │
│  │   ┌────────────────────────────────┴───────────────────────────┐  │  │
│  │   │      HTTP Broker (:49777) + Worker Instances (:49778+)    │  │  │
│  │   │                                                            │  │  │
│  │   │  execute_code  insert_cell  list_cells  get_output  ...    │  │  │
│  │   └────────────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ HTTP (MCP Protocol)
                                    ▼
                    ┌───────────────────────────────┐
                    │           AI Agent            │
                    │   (Claude Code, Cursor, etc)  │
                    └───────────────────────────────┘

How It Works

1. Extension embeds an HTTP MCP layer with broker + worker roles (default broker port 49777)
2. AI agent (Claude Code, Cursor Agent, etc.) sends tool calls via MCP protocol
3. Broker routes requests to the window that owns the target notebook URI
4. Worker uses VS Code / Cursor APIs to manipulate notebook state in its own window
5. Changes appear instantly in the editor
6. Outputs are captured and returned to the agent

This enables true interactive notebook sessions with AI agents in VS Code and Cursor.