About vscode-notebook-mcp
vscode-notebook-mcp is an MCP server in the Commerce category: exposes VSCode Jupyter notebooks to MCP-compatible AI agents, enabling them to read, edit, and run cells against the same kernel.
Install
git clone https://github.com/caryan/vscode-notebook-mcpThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Tools (5)
notebook_get_cell_contentFull source of a cell
Parameters not published.
notebook_get_cell_outputOutputs of a cell (text, errors, images as base64)
Parameters not published.
notebook_list_cellsList cells with index, kind, language, preview, execution state
Parameters not published.
notebook_list_openList all open notebooks with URI, file name, cell count, and which is active
Parameters not published.
notebook_openOpen a `.ipynb` file (absolute path, `file://` URI, or workspace-relative) so its cells become available
Parameters not published.
Ask AI
Ask AI about vscode-notebook-mcp
Powered by Claude · Grounded in docs
Security checks
- ✓README presentThe repository ships documentation.
5 checks have not been run yet.
README
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
README copy captured when this server was indexed; it may lag the repository. The original is authoritative.