Jupyter MCP Server

A notebook-specific MCP server that runs inside VS Code and lets an external agentic harness (Command Code CLI/desktop, Claude, etc.) run, edit, create, and manage the Jupyter notebook the user is actively editing — headlessly, with no approval dialogs, and no Copilot/Cursor dependency.

The objective (and how it differs from similar projects)

This extension is built for one specific workflow: an outside agent drives the notebook the human is looking at. The agent connects over MCP, operates on the same in-memory NotebookDocument the user sees in the editor, and every change appears instantly with full undo/redo.

That objective drives every design choice:

• External, harness-agnostic — any MCP client works; nothing is tied to VS Code's Copilot Chat or Cursor agents. Document editing and cell execution use the VS Code notebook API directly. Only explicit kernel configuration/startup (list_kernels(configure=true) or select_kernel(start=true)) invokes Jupyter's contributed configuration tool.

• User-editing notebook as the source of truth — tools target open NotebookDocuments, not .ipynb files on disk, so kernel state and unsaved edits are never out of sync.

• Jupyter-optional — kernel tools (list_kernels, select_kernel, run_cells, restart_kernels, interrupt_kernels) are only exposed when the Jupyter extension is installed; all document tools work with VS Code's native notebook support alone.

• Deterministic, CI-friendly testing — a shim-based MCP test suite with enforced coverage thresholds runs identically on every platform (no GUI, no VS Code download).

How this compares to similar projects

We have deliberately adopted the best ideas from the closest projects — output-capturing execution, whole-notebook reads and stable cell_id anchors — while keeping our distinct objective: serving an external harness against the user's live notebook, with no Copilot/Cursor dependency and Jupyter-optional operation.

The VS Code Marketplace also lists generic "VS Code as an MCP server" extensions (e.g. juehang/vscode-mcp-server, acomagu/vscode-as-mcp-server) that expose file/shell/diagnostics tools for plain code editing. They are not notebook-aware: they treat .ipynb files as opaque JSON, have no cell/kernel/execution model, and cannot run or capture notebook cells — so they are out of scope for this comparison.

Related MCP server: Jupyter MCP Server

Tools

Batch-oriented tools accept arrays and are grouped by owning window; cell-oriented tools target one notebook URI or notebookId per call.

Jupyter-extension guard

Tools that require a kernel — list_kernels, select_kernel, run_cells, restart_kernels, and interrupt_kernels — are only exposed when the Jupyter extension (ms-toolsai.jupyter) is installed. The remaining tools work with VS Code's native notebook support alone.

Recommended flow

1. list_notebooks → pick the notebook URI; use notebookId if that URI appears in multiple windows

2. read_notebook (or inspect_notebooks) → see the notebook's structure/state

3. edit_cells → write/change cells

4. list_kernels → enumerate read-only by default; use configure=true when a remote provider has not registered a controller yet

5. select_kernel → optionally choose a specific local or extension-provided kernel

6. run_cells → execute cells headlessly, get outputs back, and persist completed remote execution state

7. read_cell_outputs (or read_notebook with outputs) → read results

8. save_notebooks → persist; export_notebook → share

Why a VS Code extension?

Notebook execution, kernels, and the Jupyter extension's tools exist only inside the VS Code extension host. A standalone MCP process can't reach them. This extension is the bridge that lives inside VS Code and exposes them over MCP.

Why native tools instead of forwarding Copilot's?

The VS Code notebook API covers cell execution (notebook.execute), reading cells/outputs (cell.outputs, executionSummary), and kernel restart (notebook.restartKernel), so those paths remain native. Provider configuration and startup have no equivalent public notebook command, so list_kernels(configure=true) and the explicit select_kernel(start=true) path delegate that step to Jupyter's contributed configure_notebook tool. Keeping all other operations native avoids the problems with broadly forwarding Copilot tools:

• Tool-approval dialogs for execution tools invoked outside a live chat session (chat.tools.autoApprove doesn't suppress these — microsoft/vscode#319094)

• Stream requirements for interactive tools (edit/create need a chat stream)

• Coupling to Copilot Chat's tool contributions and their schemas

The native implementation is fully headless, self-contained, and works even if Copilot Chat's tools change.

Multi-window broker and takeover

All VS Code windows on the machine share one externally visible HTTP URL. The first window to bind jupyterMcp.port becomes the broker; other windows register private loopback peer endpoints and send heartbeats. The broker aggregates their open notebooks and forwards operations to the owning extension host.

When the broker window closes, the surviving peers race safely for the same configured port. One becomes the replacement broker and the others reconnect. The external URL remains unchanged, although an MCP client with an existing connection may need to reconnect after the listener changes.

If the same notebook URI is open in two windows, list_notebooks returns two entries with distinct notebookId values. Passing the plain URI produces an explicit ambiguity error; passing a notebookId routes to the selected window. Multi-notebook operations are grouped into one internal batch per owning window.

Install & run

1. Install the extension:

   • Marketplace: search for Jupyter MCP Server (publisher Happypig375) in the Extensions view, or open the marketplace page, or run code --install-extension Happypig375.vscode-jupyter-mcp-server. (Note: datalayer publishes a similarly-named standalone Jupyter Server MCP — this is the VS Code in-extension one.)

   • Local build: press F5 in this repo for an Extension Development Host (works alongside the Jupyter extension ms-toolsai.jupyter).

2. Check the $(notebook) MCP status item (hover to see the URL; click to copy it) or the Jupyter MCP Server output channel, e.g. MCP server listening on http://127.0.0.1:51303/mcp.

3. Add to Command Code:

   cmdc mcp add --transport http jupyter http://127.0.0.1:51303/mcp

   (or stdio: set jupyterMcp.transport to stdio and cmdc mcp add jupyter -- node <extension>/dist/extension.js)

Configuration

Testing

npm test runs two deterministic MCP integration suites plus a dedicated multi-window broker suite. The MCP suites exercise the exact public tool surface over real Streamable HTTP connections. The broker suite starts three independent window coordinators and verifies aggregation, duplicate-file conflicts, notebookId routing, per-window batching, and takeover of the same external port after the owner stops.

npm run coverage additionally measures coverage with c8 (sourcemap-remapped to src/**, merged across both suites) and enforces thresholds (statements/lines ≥75%, branches ≥55%, functions ≥85%) via src/test/checkCoverage.js. Both are wired into GitHub Actions CI (.github/workflows/ci.yml, matrix: ubuntu/windows/macos).

Notes / limitations

• Notebooks must be open in VS Code to be listed/read/edited (list_notebooks lists open ones).

• Requires the Jupyter extension (ms-toolsai.jupyter) for kernel-backed execution; run_cells uses the notebook's current kernel.

• select_kernel.kernelId requires an exact id returned by list_kernels and never falls back. The older run_cells.kernel field remains a best-effort label/id hint for compatibility; use select_kernel first and omit run_cells.kernel when exact selection matters.

• select_kernel is headless by default. start=true uses Jupyter's contributed notebook configuration tool and may show the provider's normal confirmation or sign-in UI (for example, Colab authentication).

• list_kernels(configure=true) may inherently require user interaction for a provider's server picker, authentication, consent, or runtime allocation. Its response includes configuration status and the refreshed controller list; plain list_kernels remains read-only.

• Cell references use 0-based indices (cellIds) — after an edit, call inspect_notebooks for fresh indices.

• The HTTP transport supports multi-window routing; stdio remains scoped to the extension host that owns its process.

• Workspace-trust / tool-approval dialogs do not apply to these native tools (they use the VS Code notebook API, not invokeTool).

License

MIT