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. The tools use the VS Code notebook API directly — no vscode.lm.invokeTool, no Copilot-tool contributions, no approval dialogs, no chat-stream requirements (microsoft/vscode#319094 is why).
• 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 (run_cells, restart_notebooks, interrupt_kernels) are only exposed when the Jupyter extension is installed; all document tools (create, read, edit, move, open, save) work with VS Code's native notebook support alone, even in an empty window with no workspace.
• 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.

Tools

All tools are multi-capable (they take arrays; a single operation is a 1-element array) — no separate singular/plural variants.

Jupyter-extension guard

Tools that require a kernel — run_cells, restart_notebooks, 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, so an empty VS Code window with no workspace and no Jupyter extension can still create a notebook from scratch and edit/read it. Install the Jupyter extension to unlock kernel-backed execution.

Recommended flow

1. get_notebooks → pick the notebook URI
2. read_notebook (or get_cells metadata) → see the notebook's structure/state
3. edit_cells → write/change cells
4. run_cells → execute cells headlessly and get outputs back
5. get_cells_output (or read_notebook with outputs) → read results
6. 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 all the functionality natively — cell execution (notebook.execute), reading cells/outputs (cell.outputs, executionSummary), kernel restart (notebook.restartKernel) — so the server implements everything itself. This avoids the problems with forwarding Copilot's tools via vscode.lm.invokeTool:

• 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 merge

Multiple VS Code windows running this extension with the same port setting merge into one MCP server:

• The first window binds the port and serves; later windows detect EADDRINUSE and merge (register in a shared registry, serve nothing locally).
• get_notebooks returns notebooks from the owning window plus all registered windows (with windowId/windowLabel).
• When the same file is open in multiple windows, the model should disambiguate (e.g. ask which window) before targeting operations; cell operations run in the window that owns the notebook.
• When the owning window closes, the registry heartbeat lets another window take over on its next attempt.

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 output channel Jupyter MCP Server for the URL, 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 (src/test/mcp.test.js + src/test/mcp.jupyter.test.js): they load the compiled extension bundle with a vscode shim and exercise every tool over a real MCP HTTP connection (connect → tools/list → tools/call). The first suite models an empty window (no workspace, no Jupyter) and asserts the tool set (kernel tools absent) plus every document operation; the second models Jupyter present and covers run_cells (output capture), read_notebook, export_notebook, search_cells, clear_outputs, get_kernel_info, interrupt_kernels, and cell_id anchors.

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 (get_notebooks lists open ones). Creating a new notebook works from the workspace (or as an untitled notebook in an empty window).
• Requires the Jupyter extension (ms-toolsai.jupyter) for kernel-backed execution; run_cells uses the notebook's current kernel.
• Cell references use 0-based indices (cellIds) — after an edit, re-fetch get_cells for fresh indices.
• Workspace-trust / tool-approval dialogs do not apply to these native tools (they use the VS Code notebook API, not invokeTool).

License

MIT