vscode-notebook-mcp
Exposes VSCode Jupyter notebooks to MCP-compatible AI agents, enabling them to read, edit, and run cells against the same kernel.
Ask AI about vscode-notebook-mcp
Powered by Claude Β· Grounded in docs
I know everything about vscode-notebook-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
| Tool | Description |
|---|---|
notebook_list_open | List all open notebooks with URI, file name, cell count, and which is active |
notebook_open | Open a .ipynb file (absolute path, file:// URI, or workspace-relative) so its cells become available |
notebook_list_cells | List cells with index, kind, language, preview, execution state |
notebook_get_cell_content | Full source of a cell |
notebook_get_cell_output | Outputs of a cell (text, errors, images as base64) |
Cell manipulation
| Tool | Description |
|---|---|
notebook_insert_cell | Insert a code or markdown cell at any position; optionally execute |
notebook_edit_cell | Replace contents of an existing cell |
notebook_delete_cell | Delete a cell by index |
Execution
| Tool | Description |
|---|---|
notebook_run_cell | Execute an existing code cell and return outputs |
notebook_clear_cell_output | Clear outputs of one cell |
notebook_clear_all_outputs | Clear outputs of every cell |
Kernel
| Tool | Description |
|---|---|
notebook_get_kernel_info | Language, status, notebook URI |
notebook_select_kernel | Programmatic by kernel_id, or open the kernel picker if omitted |
All tools accept an optional notebook_uri (omitted β uses the active notebook editor) and response_format ("markdown" or "json").
Setup
- Install the Jupyter extension in VS Code if you don't already have it.
- Build and run this extension:
Then open this folder in VS Code and press F5 to launch an Extension Development Host with the extension loaded.npm install npm run build - Add to your MCP client config:
{ "mcpServers": { "notebook": { "url": "http://127.0.0.1:49777/mcp" } } } - Open a
.ipynbfile in the Extension Development Host. Look for theπͺ :49777indicator in the status bar.
Configuration
| Setting | Default | Description |
|---|---|---|
notebook-mcp.port | 49777 | Preferred port. Auto-increments if busy (up to +99). |
Commands
Notebook MCP: Restart ServerNotebook 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.executeand waits by pollingcell.executionSummary.successfor abooleanvalue (VS Code creates the summary as soon as execution starts butsuccessonly 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 invscode.workspace.notebookDocuments(or open it); otherwise fall back tovscode.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.
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.
License
MIT
