notebookllm

Convert, inspect, and optimize Jupyter notebooks for AI Agents — Claude Code, Cursor, GitHub Copilot, Claude Desktop, VS Code, Zed, and more.

notebookllm converts notebooks to a clean, token-efficient format, reducing token usage by up to 80%. It reads and writes 8+ formats — .ipynb, percent scripts, Quarto, Markdown, Marimo, R Markdown, Deepnote, and flat scripts — through a single unified API. Use it from the CLI, Python library, or MCP server.

Important

⚡ Unified Package — One Install, Everything You Need

The standalone notebookllm-mcp package has been fully merged into the core notebookllm package. Both the Python library and MCP server now ship together. The legacy notebookllm-mcp package is deprecated — install notebookllm[mcp] to get everything.

Documentation

• CLI Reference
  • Global Options
  • Commands
• Agent Integration & Advanced Features
  • Agent Skill (SKILL.md)
  • Async Cell Execution
  • Image & Rich Output Optimization
• API Reference
  • notebookllm.models
  • notebookllm.loaders
  • notebookllm.converters
  • notebookllm.cli.commands
  • notebookllm.mcp
  • notebookllm.utils

—

Why notebookllm?

Raw .ipynb files waste AI Agent context. The JSON structure, metadata, execution counts, and base64-encoded image outputs burn tokens without adding value. notebookllm strips all that noise and produces clean, structured text that Agents can reason over effectively.

But it doesn’t stop at one-way conversion. notebookllm is a bidirectional notebook toolkit: it reads, writes, edits, searches, executes, and converts notebooks across 8+ formats. Whether you’re feeding a notebook into Claude Code, building a VS Code extension, or automating a data pipeline, notebookllm has you covered.

—

Key Features

• 8+ notebook formats — Load and save .ipynb, percent (# %%), Quarto (.qmd), Markdown (.md), Marimo (.py), R Markdown (.Rmd), Deepnote (.deepnote), and flat scripts.

• 4 output modes — minimal (source only), standard (+ metadata), full (+ outputs), token-budget (drops cells to fit a token limit).

• Smart token budget — Automatically drops lowest-priority cells to stay within an Agent’s context window.

• Token counting — Per-notebook and per-cell token measurement via tiktoken (GPT-4 cl100k_base encoding) or built-in heuristic fallback.

• Batch conversion — Convert multiple files at once with --outdir for auto-named output.

• Cell operations — Add, edit, delete, move, and search cells programmatically.

• Async cell execution — Run code cells via Jupyter kernels (thread-pooled, non-blocking, stateful across calls).

• Output summarization — Images get size metadata, DataFrames get shape/column summaries, tracebacks are compressed to the last line.

• Streaming — Handle notebooks larger than 10 MB via ijson streaming (cell-by-cell, no memory spike).

• MCP server — Expose all operations as MCP tools, resources, and prompts for AI Agent clients (Claude Desktop, VS Code, Zed, Cursor, Claude Code).

• Validation — Detect orphaned outputs, empty cells, and invalid cell types.

• Atomic writes — Crash-safe file saving via temp file + rename.

• Agent Skill — Ships with a native SKILL.md for Claude Code, Cursor, and Antigravity agents.

—

Installation

pip install notebookllm            # Core: format conversion, streaming, execution
pip install notebookllm[cli]       # + CLI (click, rich)
pip install notebookllm[mcp]       # + MCP server
pip install notebookllm[token]     # + Accurate token counting (tiktoken)
pip install notebookllm[all]       # Everything

Dependency breakdown:

Extra	Packages
(base)	nbformat, jupyter_client, ijson, pyyaml
[cli]	click, rich
[mcp]	mcp[cli]
[token]	tiktoken

Without [token], token counting uses a len(text)/4 heuristic — instant but approximate (±20%). With [token], it uses GPT-4’s cl100k_base encoding for exact counts.

—

Quick Start

CLI:

# Convert to optimized text for agents (stdout)
notebookllm convert notebook.ipynb

# Convert between formats
notebookllm convert notebook.ipynb -o output.py -f percent

# Count tokens per cell
notebookllm tokens notebook.ipynb --breakdown

# Inspect notebook structure
notebookllm inspect notebook.ipynb

See the full CLI Reference reference for all commands and options.

Python API:

from notebookllm import load_file, OutputMode

doc = load_file("notebook.ipynb")
print(doc.to_text())                                      # minimal (default)
print(doc.to_text(mode=OutputMode.FULL))                  # + cell outputs
print(doc.to_text(mode="token-budget", max_tokens=2000))  # budget mode

MCP Server:

notebookllm server          # stdio transport (Claude Desktop, Cursor, Zed)
notebookllm server --transport sse  # SSE transport (remote connections)

—

Output Modes

Controls how much detail appears in the optimized output:

minimal (default)

# %% [type] markers + source code only — cleanest for agents:

# %% [markdown]
# Data Analysis Pipeline

# %% [code]
import pandas as pd

standard

Adds execution count and cell metadata tags:

# %% [code]
# exec_count: 3
# tags: preprocessing
df = pd.read_csv("data.csv")

full

Adds cell execution outputs (stdout, results, errors):

# %% [code]
print(df.head())
# --- outputs ---
# [stdout]    col1  col2
# 0     1     2

token-budget

Drops lowest-priority cells first to stay within a max_tokens limit. Drop order: code cells without outputs → code cells with outputs → markdown.

—

Supported Formats

Extension	Format	Load	Dump
.ipynb	Jupyter Notebook (nbformat v4)	✅	✅
.py	Percent script (# %% markers)	✅	✅
.py	Marimo (@app.cell decorators)	✅	✅
.qmd	Quarto document	✅	✅
.md	Markdown with fenced code blocks	✅	✅
.Rmd	R Markdown (rmarkdown package)	✅	✅
.deepnote	Deepnote YAML project	✅	✅
.py	Flat script (one-way export)	❌	✅

—

MCP Server

The MCP server exposes all notebook operations as MCP tools, resources, and prompts for AI Agent clients (Claude Desktop, VS Code, Zed, Cursor, Claude Code).

Setup

notebookllm server                   # stdio (default)
notebookllm server --transport sse   # SSE

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "notebookllm": {
      "command": "uvx",
      "args": ["notebookllm-server"]
    }
  }
}

To pin a specific version:

{
  "mcpServers": {
    "notebookllm": {
      "command": "uvx",
      "args": ["--from", "notebookllm[all]", "notebookllm-server"]
    }
  }
}

Using pip (manual install):

pip install notebookllm[mcp]

{
  "mcpServers": {
    "notebookllm": {
      "command": "python",
      "args": ["-m", "notebookllm.mcp.server"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "mcp": {
    "servers": {
      "notebookllm": {
        "command": "uvx",
        "args": ["notebookllm-server"]
      }
    }
  }
}

Zed (~/.config/zed/mcp.json):

{
  "notebookllm": {
    "command": "uvx",
    "args": ["notebookllm-server"]
  }
}

Tools

Tool / Aliases	Description	Modifies
load / load_notebook	Load a notebook into a session	No
create / create_notebook	Create an empty notebook session in memory	No
list_sessions	List all active sessions with cell counts	No
close_session	Close session and free its kernel	No
save / save_notebook	Save session to file (atomic write)	Yes
to_text	Convert to optimized text for agents (supports max_tokens)	No
list_cells	List cells with index, type, preview	No
get_cell	Get a cell by index	No
add_cell	Add a new cell	No
edit_cell	Edit an existing cell’s source or type	Yes
delete_cell	Delete a cell by index	Yes
move_cell	Move a cell between positions	No
search_cells	Search cells by content (case-insensitive)	No
count_tokens	Count tokens in the session notebook	No
convert / convert_format	Convert session to another format	No
execute / execute_cell	Execute a code cell (async, thread-pooled)	Yes
execute_all / execute_all_cells	Execute all code cells sequentially	Yes
list_kernels	List available Jupyter kernels	No
fingerprint	Session summary (cells, imports, functions)	No
diff	Compare two sessions using unified diff	No

Resources

URI	Description
notebook://{session_id}	Full notebook as optimized text for agents
notebook://{session_id}/cells	Cell listing with index, type, preview
notebook://{session_id}/cells/{index}	Specific cell by index

Prompts

Prompt	Description
summarize_notebook(session_id)	Summarize notebook contents and purpose
review_code(session_id)	Review code quality
explain_notebook(session_id)	Explain step by step

Session Management

The MCP server maintains up to 100 concurrent sessions, persisted in a local SQLite database at ~/.local/share/notebookllm/sessions.db. Sessions have optional Jupyter kernels (if execution is used). Sessions survive server restarts — use close_session to clean up explicitly.

—

Agent Skill Integration

For autonomous AI Agents (Claude Code, Cursor, Claude Desktop, GitHub Copilot Workspaces, Antigravity), notebookllm ships with a native agent skill at skills/notebookllm/SKILL.md.

This file teaches agents exactly when and how to use notebookllm — covering CLI commands, Python API, output modes, token counting, format conversion, and MCP server integration. See Agent Integration & Advanced Features for the full guide.

—

Development

git clone https://github.com/yasirrazaa/notebookllm.git
cd notebookllm
uv sync && uv pip install -e ".[dev]"

uv run pytest                      # run tests
uv run pytest --cov=notebookllm    # with coverage
uv run pytest tests/benchmarks --benchmark-only  # benchmarks
uv run ruff check .                # lint
uv run mypy notebookllm            # type check
uv run sphinx-build -b html -E docs docs/_build/html  # build docs

—

Indices and tables

• Index

• Module Index

• Search Page

License

MIT