Notebook MCP
Provides tools for analyzing, executing, and inspecting Jupyter notebooks, including dependency graph generation, variable lineage tracking, execution state detection, and runtime kernel interaction.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Notebook MCP analyze dependencies in notebook.ipynb"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Notebook MCP
AI-Native Intelligence for Jupyter Notebooks
Notebook MCP is a Model Context Protocol (MCP) server that gives AI assistants deep semantic and runtime understanding of .ipynb notebooks.
๐ Motivation
AI coding assistants struggle with notebooks because notebooks rely heavily on execution order and hidden runtime state.
Notebook MCP bridges this gap by converting notebooks into structured, analyzable execution graphs.
Related MCP server: JupyterMCP
โจ Features
๐ Static Notebook Intelligence
Dependency graph generation
Variable lineage tracking
Focused context slicing for LLM reasoning
Deterministic notebook-to-script export
โก Execution State Awareness
Detects stale cells
Detects unexecuted cells
Generates rerun plans
๐ฌ Runtime Jupyter Integration
Execute code inside kernels
Inspect variables
Access kernel metadata
Stream execution results
๐๏ธ Architecture
Notebook โ MCP Server โ AI AssistantCore Components:
AST Analysis Engine
Dependency Graph Builder
Execution State Engine
Jupyter Kernel WebSocket Client
Context Builder for LLMs
๐ฆ Installation
npm (Recommended)
npm install -g @akram1110/notebook-mcpPython Backend
pip install notebook-mcpโ๏ธ Running Server
notebook-mcp๐งน Uninstallation
Notebook MCP installs components via both npm and pip.
Follow the steps below to fully remove the tool.
Step 1 โ Remove npm Wrapper
npm uninstall -g @akram1110/notebook-mcpStep 2 โ Remove Python Backend
pip uninstall notebook-mcpor
python -m pip uninstall notebook-mcpStep 3 โ Confirm Removal
notebook-mcpExpected output:
command not foundStep 4 โ Windows Only: Remove Leftover Executables
Python sometimes leaves launcher files behind.
Check:
where notebook-mcpIf found, delete from:
<python_install_dir>\Scripts\Example:
C:\Users\<username>\AppData\Local\Programs\Python\Python311\Scripts\Step 5 โ Clean Corrupted pip Distribution Warnings
If pip shows:
WARNING: Ignoring invalid distribution ~Delete folders beginning with ~ inside:
<python_install_dir>\Lib\site-packages\Then verify:
pip checkStep 6 โ Optional Cache Cleanup
pip cache purgeAfter completing these steps, Notebook MCP will be fully removed from your system.
๐ Cursor Integration
{
"mcpServers": {
"notebook": {
"command": "notebook-mcp"
}
}
}๐งช Example MCP Tools
Tool | Description |
notebook_analyze | Builds dependency graph |
notebook_context | Generates focused context |
notebook_state | Detects execution state |
notebook_rerun_plan | Suggests rerun order |
jupyter_execute | Executes kernel code |
jupyter_inspect | Inspects runtime variables |
๐ง Jupyter Integration
Set environment variables:
JUPYTER_BASE_URL=http://localhost:8888
JUPYTER_TOKEN=<token>๐ Tech Stack
Python
Model Context Protocol (MCP)
AST Analysis
NetworkX Graphs
Jupyter Kernel Protocol
Node.js CLI Distribution
๐ฃ๏ธ Roadmap
Output semantic analysis
Notebook replay engine
Incremental notebook graph caching
Binary distribution support
๐ค Contributing
Issues and PRs welcome.
๐ License
MIT License
Available Tools
13 toolsjupyter_executeC
Execute code on a Jupyter kernel via Jupyter Server websocket channels.
Requires:
JUPYTER_BASE_URL
JUPYTER_TOKEN (optional)
Inputs: kernel_id (required), code (required), timeout_s.
jupyter_execution_cancelD
Inputs: execution_id (required).
jupyter_execution_outputD
Inputs: execution_id (required).
jupyter_execution_statusD
Inputs: execution_id (required).
jupyter_execution_submitD
Inputs: kernel_id (required), code (required), timeout_s.
jupyter_get_kernelC
Get kernel metadata from Jupyter Server.
Inputs: kernel_id (required).
jupyter_inspectC
Inspect an expression on a kernel using user_expressions (repr + type).
Requires:
JUPYTER_BASE_URL
JUPYTER_TOKEN (optional)
Inputs: kernel_id (required), expression (required), timeout_s.
jupyter_list_sessionsB
List Jupyter Server sessions (requires JUPYTER_BASE_URL and optional JUPYTER_TOKEN).
Inputs: no named parameters. Returns: result
notebook_analyzeC
Analyze a notebook and return structured cell info and dependency edges.
Inputs: path (required), strip_outputs, include_markdown.
notebook_contextC
Return a focused, dependency-aware context slice for a given cell.
Inputs: path (required), focus_cell_id (required), max_cells, include_markdown.
notebook_export_scriptC
Export notebook code to a best-effort deterministic Python script.
Inputs: path (required), include_markdown_as_comments. Returns: result
notebook_rerun_planC
Recommend a rerun plan (best-effort offline) for a focus cell.
Inputs: path (required), focus_cell_id (required), strip_outputs, include_markdown.
notebook_stateC
Compute best-effort execution state for each cell using execution_count + dependency edges.
Inputs: path (required), strip_outputs, include_markdown.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 13 tools
Most tools have distinct purposes (e.g., execute vs. inspect vs. analyze), but jupyter_execute and jupyter_execution_submit could be confused, and jupyter_execution_output overlaps somewhat with jupyter_inspect.
Uses two prefixes (jupyter_, notebook_) inconsistently; within jupyter_ group, some are verbs (execute, get_kernel) and others are noun phrases (execution_cancel, execution_output), breaking the pattern.
13 tools is well-scoped for a Jupyter notebook server, covering execution, kernel inspection, session management, and notebook analysis without being overwhelming.
Covers core notebook interactions (execute, analyze, export, state) but lacks tools for creating or deleting notebooks/kernels, and no direct session shutdown.
Related MCP Connectors
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Codebase intelligence for AI agents โ dead code, blast radius, ownership.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables programmatic interaction with Jupyter notebooks, allowing reading, editing, and executing cells via Claude.634 PyPI34MIT
- AlicenseAqualityDmaintenanceEnables AI agents to create, read, edit, and execute Jupyter notebook cells, manage kernels, and connect to remote Jupyter servers.2122 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to execute Jupyter notebook cells with persistent kernel state, output persistence, and structured JSON control surface.2-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to read, edit, execute cells, and capture outputs from Jupyter notebooks directly within VS Code or Cursor via the Model Context Protocol.18MIT