vscode-notebook-mcp

A VS Code extension that exposes the Jupyter notebooks in your VSCode editor to MCP-compatible AI agents (e.g. Claude Code). The agent reads, edits, and runs cells against the same kernel VS Code is using.

Status: pre-alpha, single-developer project. Built fresh; not a fork.

Tools (13)

Discovery

Cell manipulation

Execution

Kernel

All tools accept an optional notebook_uri (omitted → uses the active notebook editor) and response_format ("markdown" or "json").

Setup

1. Install the Jupyter extension in VS Code if you don't already have it.

2. Build and run this extension:

   npm install
   npm run build

   Then open this folder in VS Code and press F5 to launch an Extension Development Host with the extension loaded.

3. Add to your MCP client config:

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

4. Open a .ipynb file in the Extension Development Host. Look for the 🪐 :49777 indicator in the status bar.

Configuration

Commands

• Notebook MCP: Restart Server

• Notebook MCP: Show Server Info

Architecture

┌─────────────────────────────────────────────────────────┐
│                    VS Code window                       │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Jupyter extension (ms-toolsai.jupyter)           │  │
│  │                                                   │  │
│  │  Notebook document  ◄──►  Kernel  ──►  Outputs    │  │
│  └───────────────────────────────────────────────────┘  │
│                          ▲                              │
│                          │ vscode.NotebookEdit,         │
│                          │ notebook.cell.execute,       │
│                          │ jupyter.kernels.getKernel    │
│                          │                              │
│  ┌───────────────────────┴───────────────────────────┐  │
│  │  This extension                                   │  │
│  │                                                   │  │
│  │   HTTP server :49777  ──►  MCP tools (12)         │  │
│  │   (StreamableHTTPServerTransport)                 │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                              │ HTTP (MCP protocol)
                              ▼
                ┌───────────────────────────────┐
                │   AI agent                    │
                │   (Claude Code, Cursor, etc.) │
                └───────────────────────────────┘

Implementation notes

• Writes go through vscode.NotebookEdit + vscode.WorkspaceEdit, preserving undo/redo.

• Execution dispatches notebook.cell.execute and waits by polling cell.executionSummary.success for a boolean value (VS Code creates the summary as soon as execution starts but success only becomes a boolean when the kernel finishes).

• Inserted cells are tagged with a metadata id so the executor can find them again after the index shifts due to other concurrent edits.

• Multi-notebook: every tool accepts notebook_uri. Resolution: explicit URI → look up in vscode.workspace.notebookDocuments (or open it); otherwise fall back to vscode.window.activeNotebookEditor.

Development

npm install
npm run build       # esbuild bundle
npm run watch       # rebuild on change
npm run typecheck   # tsc --noEmit
npm test            # vitest (no tests yet)

Press F5 in VS Code to launch the Extension Development Host.

Building a VSIX

To produce an installable .vsix file:

npx @vscode/vsce package

This runs vscode:prepublish (which builds via esbuild) and writes vscode-notebook-mcp-<version>.vsix to the repo root. Install it with:

code --install-extension vscode-notebook-mcp-<version>.vsix

.vscodeignore keeps the package small by excluding TS sources, node_modules, source maps, and dev configs — only the bundled dist/, package.json, README.md, and LICENSE are shipped.

References

Other projects along similar lines to this project:

• datalayer/jupyter-mcp-server — MCP server that talks to a running Jupyter server via HTTP/WebSocket.

• olavocarvalho/vscode-runtime-notebook-mcp — similar architecture as this project (VS Code Notebook API + embedded HTTP MCP server).

I built this fresh to learn and so I have room to tweak the design and develop new features such as reading Plotly images.

License

MIT