Skip to main content
Glama

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 Assistant

Core Components:

  • AST Analysis Engine

  • Dependency Graph Builder

  • Execution State Engine

  • Jupyter Kernel WebSocket Client

  • Context Builder for LLMs


๐Ÿ“ฆ Installation

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

Available Tools

13 tools
jupyter_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

    C2.4/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    13 tools is well-scoped for a Jupyter notebook server, covering execution, kernel inspection, session management, and notebook analysis without being overwhelming.

    Completeness4/5

    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

    Related MCP Servers