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.

---

✨ 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 Assistant

Core 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-mcp

---

Python 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-mcp

---

Step 2 — Remove Python Backend

pip uninstall notebook-mcp

or

python -m pip uninstall notebook-mcp

---

Step 3 — Confirm Removal

notebook-mcp

Expected output:

command not found

---

Step 4 — Windows Only: Remove Leftover Executables

Python sometimes leaves launcher files behind.

Check:

where notebook-mcp

If 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 check

---

Step 6 — Optional Cache Cleanup

pip cache purge

---

After 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