How do I install Notebookllm?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Notebookllm need an API key?

No required environment variable is listed on this record.

What transport does Notebookllm use?

Notebookllm runs locally over stdio.

When was Notebookllm last checked?

Last checked 2026-10-27. Jupyter notebooks, made agent-ready. 8+ formats · MCP server · async execution · token budgeting.

Notebookllm MCP server

notebookllm

⚡ Unified Package — One Install, Everything You Need

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

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

notebookllm is the Swiss Army knife for notebook manipulation. It converts notebooks to a clean, Agent-optimized plain-text format — reducing token usage by up to 80% — and reads/writes 8+ formats through a single unified API. Use it from the CLI, as a Python library, or as an MCP server for AI Agent integration.

Key Features

8+ Notebook Formats — Load and save .ipynb, percent (# %%), Quarto (.qmd), Markdown (.md), Marimo (.py), R Markdown (.Rmd), Deepnote (.deepnote), and flat scripts. One API to rule them all.
AI Agent–Optimized Output — Strip JSON noise, metadata, and base64 blobs. Produce clean text that AI Agents can reason over effectively. Four verbosity modes: minimal, standard, full, and token-budget.
Smart Token Budget — Automatically drop lowest-priority cells to fit within a token limit. Markdown (explanatory) → code with outputs → bare code (dropped first).
Token Counting — Per-notebook and per-cell token measurement via tiktoken (GPT-4 cl100k_base) or built-in heuristic fallback.
Intelligent Output Summarization — DataFrames get shape/column summaries, images get size metadata, tracebacks get compressed to the last line.
Batch Conversion — Convert entire directories of notebooks in one command.
Cell Operations — Add, edit, delete, move, search, and execute cells programmatically.
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 any MCP-compatible AI Agent client (Claude Desktop, VS Code, Zed, Cursor, Claude Code).
Validation & Atomic Writes — Detect orphaned outputs, empty cells, and invalid types. Crash-safe file saves via temp-file + rename.

Quick Start

pip install notebookllm[cli]

# Convert a notebook to Agent-optimized text
notebookllm convert notebook.ipynb

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

# Count tokens
notebookllm tokens notebook.ipynb --breakdown

# Inspect notebook structure
notebookllm inspect notebook.ipynb

from notebookllm import load_file

# Load any notebook format — auto-detected
doc = load_file("notebook.ipynb")

# Convert to AI Agent–optimized text
print(doc.to_text())                                      # minimal (default)
print(doc.to_text(mode="token-budget", max_tokens=2000))  # budget mode

Why notebookllm?

Raw .ipynb files waste AI Agent context. The JSON structure, execution metadata, 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.

Installation

Migrating from notebookllm-mcp? The separate MCP package is now deprecated. Everything is built in. Just pip install notebookllm[mcp].

pip install notebookllm            # Core: format conversion, streaming, execution
pip install notebookllm[cli]       # + CLI (click, rich tables, syntax highlighting)
pip install notebookllm[mcp]       # + MCP server for AI Agent integration
pip install notebookllm[token]     # + Accurate token counting via tiktoken
pip install notebookllm[all]       # Everything (CLI + MCP + token)

Dependency breakdown:

Extra	What you get
(base)	`nbformat`, `jupyter_client`, `ijson`, `pyyaml` — format conversion, streaming, cell execution
`[cli]`	`click`, `rich` — CLI with formatted output
`[mcp]`	`mcp[cli]` — MCP server for AI Agent clients
`[token]`	`tiktoken` — GPT-4 token counting (without it, uses `len(text)/4` heuristic, ±20%)

CLI Reference

`notebookllm convert`

Convert notebook(s) between formats or to Agent-optimized text.

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

# Single file to a specific format
notebookllm convert notebook.ipynb -o output.py -f percent
notebookllm convert notebook.ipynb -o output.qmd -f quarto

# Output verbosity
notebookllm convert notebook.ipynb              # minimal (default)
notebookllm convert notebook.ipynb -m standard  # + execution counts, tags
notebookllm convert notebook.ipynb -m full      # + cell outputs

# Batch: multiple files to stdout
notebookllm convert a.ipynb b.qmd c.py

# Batch: multiple files to directory (auto-named)
notebookllm convert *.ipynb --outdir ./out
notebookllm convert a.ipynb b.qmd --outdir ./out -f markdown

`notebookllm inspect`

Show notebook structure — format, language, cell count, and a formatted table of cells with previews.

notebookllm inspect notebook.ipynb

`notebookllm search`

Search cells by content (case-insensitive substring match). Filter by type with -t.

notebookllm search notebook.ipynb "import pandas"
notebookllm search notebook.ipynb "def train" -t code

`notebookllm get`

Extract a single cell by 0-based index. Rich syntax highlighting included.

notebookllm get notebook.ipynb 3

`notebookllm tokens`

Estimate token usage. Uses tiktoken when available, falls back to heuristic.

notebookllm tokens notebook.ipynb              # total tokens
notebookllm tokens notebook.ipynb --breakdown  # per-cell table
notebookllm tokens notebook.ipynb -m full      # count with outputs

`notebookllm server`

Start the MCP server for AI Agent integration.

notebookllm server                    # stdio (default — Claude Desktop, VS Code, Zed)
notebookllm server --transport sse    # SSE (HTTP-based connections)

Python API

Loading and Saving

from notebookllm import NotebookDocument, load_file, dump_file, loads_text

# Load — auto-detects format from extension
doc = load_file("notebook.ipynb")
doc = load_file("analysis.qmd")
doc = load_file("report.Rmd")

# Load from string with auto-detection
doc = loads_text("# %% [code]\nprint('hi')\n")  # auto-detected as "percent"

# Explicit format
doc = loads_text(text, source_format="quarto")

# Convenience class methods
doc = NotebookDocument.from_file("notebook.ipynb")
doc = NotebookDocument.from_text(text, source_format="quarto")

# Save — auto-detects format from extension
doc.to_file("output.ipynb")
doc.to_file("output.py", fmt="percent")

# Serialize/deserialize (CIR JSON)
json_str = doc.to_json()
restored = NotebookDocument.from_json(json_str)

Converting to Optimized Text for Agents

from notebookllm import OutputMode

# Four output verbosity modes
text = doc.to_text()                                       # minimal (default)
text = doc.to_text(mode=OutputMode.STANDARD)               # + execution counts, tags
text = doc.to_text(mode=OutputMode.FULL)                   # + cell outputs
text = doc.to_text(mode="token-budget", max_tokens=5000)   # budget mode

Output examples:

# MINIMAL — clean, token-efficient
# %% [code]
import pandas as pd
df = pd.read_csv("data.csv")

# STANDARD — includes metadata
# %% [code]
# exec_count: 3
# tags: preprocessing, cleaning
df = df.dropna()

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

Token Counting

from notebookllm import tokenize_notebook, count_tokens

# Notebook-level token analysis
report = tokenize_notebook(doc, mode="minimal")
print(report.token_summary)  # "Total: 420 tokens across 8 cells (minimal mode)"
for ct in report.cell_tokens:
    print(f"  [{ct.cell_index}] {ct.cell_type}: {ct.tokens} tokens — {ct.preview}")

# Single string
n = count_tokens("hello world")  # 2 tokens (tiktoken) or 3 (fallback)

# Convenience method on the document
report = doc.token_breakdown(mode="minimal")

Cell Operations

from notebookllm import Cell, CellType

# Add cells
doc.add_cell(Cell(cell_type=CellType.CODE, source="x = 1"))
doc.add_cell(Cell(cell_type=CellType.MARKDOWN, source="# Title"), position=0)

# Edit
doc.edit_cell(0, source="x = 2")
doc.edit_cell(0, source="# New", cell_type=CellType.MARKDOWN)

# Delete and move
doc.delete_cell(2)
doc.move_cell(from_index=0, to_index=2)

# Get
cell = doc.get_cell(0)
print(cell.source, cell.cell_type, cell.execution_count)

Search and Filter

# Search with optional type filter
results = doc.search("import pandas", cell_type=CellType.CODE)
for idx, cell in results:
    print(f"[{idx}] {cell.source[:60]}")

# Filter
code_cells = doc.filter_cells(cell_type=CellType.CODE)
matches = doc.filter_cells(query="train")

Inspection

print(len(doc.cells))           # cell count
print(doc.source_format)        # "ipynb", "percent", "quarto", etc.
print(doc.language)             # "python", "r", etc.
print(doc.kernel_name)          # "python3", etc.

Validation

from notebookllm.utils.validation import validate_notebook

report = validate_notebook(doc)
print(report.summary)       # "Validation passed." or "Validation found 2 errors, 3 warnings."
print(report.format_text()) # human-readable error/warning listing
print(report.is_valid)      # True if no errors

Supported Formats

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

MCP Server for AI Agent Integration

The MCP server exposes every notebookllm operation as MCP tools, resources, and prompts. This lets any MCP-compatible AI Agent client (Claude Desktop, VS Code, Zed, Cursor, Claude Code) manipulate notebooks on your behalf.

Setup

Start the MCP server:

notebookllm server

Configuration

Configure your MCP client using either uvx (recommended) or pip with python -m.

Using uvx (zero-config, no manual install)

uvx automatically fetches notebookllm from PyPI and runs the server in an isolated environment.

Claude Desktop (claude_desktop_config.json):

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

To pin a specific version or extras:

{
  "mcpServers": {
    "notebookllm": {
      "command": "uvx",
      "args": ["--from", "notebookllm[all]", "notebookllm-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"]
  }
}

Using pip (manual install)

Install the package first, then reference the installed server module:

pip install notebookllm[mcp]

Claude Desktop (claude_desktop_config.json):

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

VS Code (.vscode/mcp.json):

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

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

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

Tools (26 total — 20 unique + 6 aliases)

Primary Name	Description	Destructive
`load`	Load a notebook file into a new session	No
`create`	Create an empty notebook session	No
`list_sessions`	List all active sessions	No
`close_session`	Close session and clean up its kernel	No
`save`	Save session to file	Yes
`to_text`	Convert to Agent-optimized text	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	Yes
`delete_cell`	Delete a cell	Yes
`move_cell`	Move a cell to a new position	No
`search_cells`	Search cells by content	No
`count_tokens`	Count tokens in a session	No
`convert`	Convert session to another format	No
`execute`	Execute a code cell via Jupyter kernel	Yes
`execute_all`	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

Aliases (backward-compatible with old notebookllm-mcp): load_notebook, create_notebook, save_notebook, convert_format, execute_cell, execute_all_cells.

Resources

URI	Description
`notebook://{session_id}`	Full notebook as Agent-optimized text
`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 in a notebook
`explain_notebook(session_id)`	Explain the notebook step by step

Session Management

The MCP server maintains up to 100 concurrent sessions, persisted to a local SQLite database at ~/.local/share/notebookllm/sessions.db. Sessions survive server restarts. Each session optionally has a Jupyter kernel for code execution. Sessions are auto-evicted (oldest first) when the limit is reached.

Agent Skill

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

This skill document teaches AI Agents exactly how to use notebookllm to manipulate and inspect notebooks on your behalf. To equip your agent:

Ensure the skills/ directory is discoverable by your agent
Or instruct the agent to read skills/notebookllm/SKILL.md directly

The skill covers: CLI commands, Python API usage, output modes, token counting, format conversion, and MCP server integration.

Output Modes

Controls how much detail appears in the Agent-optimized text output:

Mode	What's Included	Best For
`minimal`	`# %% [type]` markers + source code only	Agent input — cleanest, most token-efficient
`standard`	Adds execution count and metadata tags	Understanding notebook execution history
`full`	Adds all cell outputs (stdout, results, errors)	Complete notebook state analysis
`token-budget`	Drops lowest-priority cells to fit `max_tokens`	Strict context window limits

Token-budget drop priority (highest-value kept longest):

Markdown cells (explanatory — never dropped if only one remains)
Code cells with outputs (executed, have results)
Code cells without outputs (scaffolding — dropped first)

Output Summarization

When using token-budget mode or with summarize_outputs=True, long and rich outputs are automatically compressed:

DataFrames: Shape and column names extracted from the ASCII repr — # [DataFrame(1000, 5)] Columns: col1, col2, col3 (values hidden)
Images: MIME type and approximate size — # [Plot: image/png, ~42KB]
Tracebacks: Last line only — # [error] ValueError: invalid literal for int()
Long text: Truncated at 500 characters with a remainder note

Cell Execution

Run code cells via Jupyter kernels through the MCP server's execute and execute_all tools. Execution is async and thread-pooled, keeping the server responsive. Kernels are started lazily per session and cleaned up when the session is closed.

# via MCP server tools:
#   execute(session_id="...", index=0)
#   execute_all(session_id="...")
#   list_kernels()

Development

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

# Run tests
uv run pytest

# With coverage
uv run pytest --cov=notebookllm

# Run benchmarks
uv run pytest tests/benchmarks --benchmark-only

# Lint and type check
uv run ruff check .
uv run mypy notebookllm

# Build this documentation
uv run sphinx-build -b html -E docs docs/_build

Architecture Overview

                 ┌──────────────┐
                 │  CLI (click) │
                 └──────┬───────┘
                        │
┌──────────┐    ┌───────┴────────┐    ┌──────────────┐
│  MCP     │◄──►│  Loaders/      │◄──►│  Notebook    │
│  Server  │    │  Dumpers       │    │  Document    │
│          │    │  (8 formats)   │    │  (CIR model) │
└──────────┘    └───────┬────────┘    └──────┬───────┘
                        │                    │
                 ┌───────┴────────┐    ┌──────┴────────┐
                 │  Format        │    │  Agent        │
                 │  Detection     │    │  Optimizer    │
                 └────────────────┘    └──────┬────────┘
                                              │
                                     ┌────────┴────────┐
                                     │  Token Counter  │
                                     │  (tiktoken)     │
                                     └─────────────────┘

License

MIT — see LICENSE for details.

notebookllm

⚡ Unified Package — One Install, Everything You Need

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

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

Key Features

8+ Notebook Formats — Load and save .ipynb, percent (# %%), Quarto (.qmd), Markdown (.md), Marimo (.py), R Markdown (.Rmd), Deepnote (.deepnote), and flat scripts. One API to rule them all.
AI Agent–Optimized Output — Strip JSON noise, metadata, and base64 blobs. Produce clean text that AI Agents can reason over effectively. Four verbosity modes: minimal, standard, full, and token-budget.
Smart Token Budget — Automatically drop lowest-priority cells to fit within a token limit. Markdown (explanatory) → code with outputs → bare code (dropped first).
Token Counting — Per-notebook and per-cell token measurement via tiktoken (GPT-4 cl100k_base) or built-in heuristic fallback.
Intelligent Output Summarization — DataFrames get shape/column summaries, images get size metadata, tracebacks get compressed to the last line.
Batch Conversion — Convert entire directories of notebooks in one command.
Cell Operations — Add, edit, delete, move, search, and execute cells programmatically.
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 any MCP-compatible AI Agent client (Claude Desktop, VS Code, Zed, Cursor, Claude Code).
Validation & Atomic Writes — Detect orphaned outputs, empty cells, and invalid types. Crash-safe file saves via temp-file + rename.

Quick Start

pip install notebookllm[cli]

# Convert a notebook to Agent-optimized text
notebookllm convert notebook.ipynb

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

# Count tokens
notebookllm tokens notebook.ipynb --breakdown

# Inspect notebook structure
notebookllm inspect notebook.ipynb

from notebookllm import load_file

# Load any notebook format — auto-detected
doc = load_file("notebook.ipynb")

# Convert to AI Agent–optimized text
print(doc.to_text())                                      # minimal (default)
print(doc.to_text(mode="token-budget", max_tokens=2000))  # budget mode

Why notebookllm?

Installation

Migrating from notebookllm-mcp? The separate MCP package is now deprecated. Everything is built in. Just pip install notebookllm[mcp].

pip install notebookllm            # Core: format conversion, streaming, execution
pip install notebookllm[cli]       # + CLI (click, rich tables, syntax highlighting)
pip install notebookllm[mcp]       # + MCP server for AI Agent integration
pip install notebookllm[token]     # + Accurate token counting via tiktoken
pip install notebookllm[all]       # Everything (CLI + MCP + token)

Dependency breakdown:

Extra	What you get
(base)	`nbformat`, `jupyter_client`, `ijson`, `pyyaml` — format conversion, streaming, cell execution
`[cli]`	`click`, `rich` — CLI with formatted output
`[mcp]`	`mcp[cli]` — MCP server for AI Agent clients
`[token]`	`tiktoken` — GPT-4 token counting (without it, uses `len(text)/4` heuristic, ±20%)

CLI Reference

`notebookllm convert`

Convert notebook(s) between formats or to Agent-optimized text.

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

# Single file to a specific format
notebookllm convert notebook.ipynb -o output.py -f percent
notebookllm convert notebook.ipynb -o output.qmd -f quarto

# Output verbosity
notebookllm convert notebook.ipynb              # minimal (default)
notebookllm convert notebook.ipynb -m standard  # + execution counts, tags
notebookllm convert notebook.ipynb -m full      # + cell outputs

# Batch: multiple files to stdout
notebookllm convert a.ipynb b.qmd c.py

# Batch: multiple files to directory (auto-named)
notebookllm convert *.ipynb --outdir ./out
notebookllm convert a.ipynb b.qmd --outdir ./out -f markdown

`notebookllm inspect`

Show notebook structure — format, language, cell count, and a formatted table of cells with previews.

notebookllm inspect notebook.ipynb

`notebookllm search`

Search cells by content (case-insensitive substring match). Filter by type with -t.

notebookllm search notebook.ipynb "import pandas"
notebookllm search notebook.ipynb "def train" -t code

`notebookllm get`

Extract a single cell by 0-based index. Rich syntax highlighting included.

notebookllm get notebook.ipynb 3

`notebookllm tokens`

Estimate token usage. Uses tiktoken when available, falls back to heuristic.

notebookllm tokens notebook.ipynb              # total tokens
notebookllm tokens notebook.ipynb --breakdown  # per-cell table
notebookllm tokens notebook.ipynb -m full      # count with outputs

`notebookllm server`

Start the MCP server for AI Agent integration.

notebookllm server                    # stdio (default — Claude Desktop, VS Code, Zed)
notebookllm server --transport sse    # SSE (HTTP-based connections)

Python API

Loading and Saving

from notebookllm import NotebookDocument, load_file, dump_file, loads_text

# Load — auto-detects format from extension
doc = load_file("notebook.ipynb")
doc = load_file("analysis.qmd")
doc = load_file("report.Rmd")

# Load from string with auto-detection
doc = loads_text("# %% [code]\nprint('hi')\n")  # auto-detected as "percent"

# Explicit format
doc = loads_text(text, source_format="quarto")

# Convenience class methods
doc = NotebookDocument.from_file("notebook.ipynb")
doc = NotebookDocument.from_text(text, source_format="quarto")

# Save — auto-detects format from extension
doc.to_file("output.ipynb")
doc.to_file("output.py", fmt="percent")

# Serialize/deserialize (CIR JSON)
json_str = doc.to_json()
restored = NotebookDocument.from_json(json_str)

Converting to Optimized Text for Agents

from notebookllm import OutputMode

# Four output verbosity modes
text = doc.to_text()                                       # minimal (default)
text = doc.to_text(mode=OutputMode.STANDARD)               # + execution counts, tags
text = doc.to_text(mode=OutputMode.FULL)                   # + cell outputs
text = doc.to_text(mode="token-budget", max_tokens=5000)   # budget mode

Output examples:

# MINIMAL — clean, token-efficient
# %% [code]
import pandas as pd
df = pd.read_csv("data.csv")

# STANDARD — includes metadata
# %% [code]
# exec_count: 3
# tags: preprocessing, cleaning
df = df.dropna()

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

Token Counting

from notebookllm import tokenize_notebook, count_tokens

# Notebook-level token analysis
report = tokenize_notebook(doc, mode="minimal")
print(report.token_summary)  # "Total: 420 tokens across 8 cells (minimal mode)"
for ct in report.cell_tokens:
    print(f"  [{ct.cell_index}] {ct.cell_type}: {ct.tokens} tokens — {ct.preview}")

# Single string
n = count_tokens("hello world")  # 2 tokens (tiktoken) or 3 (fallback)

# Convenience method on the document
report = doc.token_breakdown(mode="minimal")

Cell Operations

from notebookllm import Cell, CellType

# Add cells
doc.add_cell(Cell(cell_type=CellType.CODE, source="x = 1"))
doc.add_cell(Cell(cell_type=CellType.MARKDOWN, source="# Title"), position=0)

# Edit
doc.edit_cell(0, source="x = 2")
doc.edit_cell(0, source="# New", cell_type=CellType.MARKDOWN)

# Delete and move
doc.delete_cell(2)
doc.move_cell(from_index=0, to_index=2)

# Get
cell = doc.get_cell(0)
print(cell.source, cell.cell_type, cell.execution_count)

Search and Filter

# Search with optional type filter
results = doc.search("import pandas", cell_type=CellType.CODE)
for idx, cell in results:
    print(f"[{idx}] {cell.source[:60]}")

# Filter
code_cells = doc.filter_cells(cell_type=CellType.CODE)
matches = doc.filter_cells(query="train")

Inspection

print(len(doc.cells))           # cell count
print(doc.source_format)        # "ipynb", "percent", "quarto", etc.
print(doc.language)             # "python", "r", etc.
print(doc.kernel_name)          # "python3", etc.

Validation

from notebookllm.utils.validation import validate_notebook

report = validate_notebook(doc)
print(report.summary)       # "Validation passed." or "Validation found 2 errors, 3 warnings."
print(report.format_text()) # human-readable error/warning listing
print(report.is_valid)      # True if no errors

Supported Formats

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

MCP Server for AI Agent Integration

Setup

Start the MCP server:

notebookllm server

Configuration

Configure your MCP client using either uvx (recommended) or pip with python -m.

Using uvx (zero-config, no manual install)

uvx automatically fetches notebookllm from PyPI and runs the server in an isolated environment.

Claude Desktop (claude_desktop_config.json):

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

To pin a specific version or extras:

{
  "mcpServers": {
    "notebookllm": {
      "command": "uvx",
      "args": ["--from", "notebookllm[all]", "notebookllm-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"]
  }
}

Using pip (manual install)

Install the package first, then reference the installed server module:

pip install notebookllm[mcp]

Claude Desktop (claude_desktop_config.json):

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

VS Code (.vscode/mcp.json):

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

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

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

Tools (26 total — 20 unique + 6 aliases)

Primary Name	Description	Destructive
`load`	Load a notebook file into a new session	No
`create`	Create an empty notebook session	No
`list_sessions`	List all active sessions	No
`close_session`	Close session and clean up its kernel	No
`save`	Save session to file	Yes
`to_text`	Convert to Agent-optimized text	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	Yes
`delete_cell`	Delete a cell	Yes
`move_cell`	Move a cell to a new position	No
`search_cells`	Search cells by content	No
`count_tokens`	Count tokens in a session	No
`convert`	Convert session to another format	No
`execute`	Execute a code cell via Jupyter kernel	Yes
`execute_all`	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

Aliases (backward-compatible with old notebookllm-mcp): load_notebook, create_notebook, save_notebook, convert_format, execute_cell, execute_all_cells.

Resources

URI	Description
`notebook://{session_id}`	Full notebook as Agent-optimized text
`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 in a notebook
`explain_notebook(session_id)`	Explain the notebook step by step

Session Management

Agent Skill

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

This skill document teaches AI Agents exactly how to use notebookllm to manipulate and inspect notebooks on your behalf. To equip your agent:

Ensure the skills/ directory is discoverable by your agent
Or instruct the agent to read skills/notebookllm/SKILL.md directly

The skill covers: CLI commands, Python API usage, output modes, token counting, format conversion, and MCP server integration.

Output Modes

Controls how much detail appears in the Agent-optimized text output:

Mode	What's Included	Best For
`minimal`	`# %% [type]` markers + source code only	Agent input — cleanest, most token-efficient
`standard`	Adds execution count and metadata tags	Understanding notebook execution history
`full`	Adds all cell outputs (stdout, results, errors)	Complete notebook state analysis
`token-budget`	Drops lowest-priority cells to fit `max_tokens`	Strict context window limits

Token-budget drop priority (highest-value kept longest):

Markdown cells (explanatory — never dropped if only one remains)
Code cells with outputs (executed, have results)
Code cells without outputs (scaffolding — dropped first)

Output Summarization

When using token-budget mode or with summarize_outputs=True, long and rich outputs are automatically compressed:

DataFrames: Shape and column names extracted from the ASCII repr — # [DataFrame(1000, 5)] Columns: col1, col2, col3 (values hidden)
Images: MIME type and approximate size — # [Plot: image/png, ~42KB]
Tracebacks: Last line only — # [error] ValueError: invalid literal for int()
Long text: Truncated at 500 characters with a remainder note

Cell Execution

# via MCP server tools:
#   execute(session_id="...", index=0)
#   execute_all(session_id="...")
#   list_kernels()

Development

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

# Run tests
uv run pytest

# With coverage
uv run pytest --cov=notebookllm

# Run benchmarks
uv run pytest tests/benchmarks --benchmark-only

# Lint and type check
uv run ruff check .
uv run mypy notebookllm

# Build this documentation
uv run sphinx-build -b html -E docs docs/_build

Architecture Overview

                 ┌──────────────┐
                 │  CLI (click) │
                 └──────┬───────┘
                        │
┌──────────┐    ┌───────┴────────┐    ┌──────────────┐
│  MCP     │◄──►│  Loaders/      │◄──►│  Notebook    │
│  Server  │    │  Dumpers       │    │  Document    │
│          │    │  (8 formats)   │    │  (CIR model) │
└──────────┘    └───────┬────────┘    └──────┬───────┘
                        │                    │
                 ┌───────┴────────┐    ┌──────┴────────┐
                 │  Format        │    │  Agent        │
                 │  Detection     │    │  Optimizer    │
                 └────────────────┘    └──────┬────────┘
                                              │
                                     ┌────────┴────────┐
                                     │  Token Counter  │
                                     │  (tiktoken)     │
                                     └─────────────────┘

License

MIT — see LICENSE for details.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Notebookllm?

Does Notebookllm need an API key?

What transport does Notebookllm use?

When was Notebookllm last checked?

Documentation

notebookllm

Key Features

Quick Start

Why notebookllm?

Installation

CLI Reference

notebookllm convert

notebookllm inspect

notebookllm search

notebookllm get

notebookllm tokens

notebookllm server

Python API

Loading and Saving

Converting to Optimized Text for Agents

Token Counting

Cell Operations

Search and Filter

Inspection

Validation

Supported Formats

MCP Server for AI Agent Integration

Setup

Configuration

Using uvx (zero-config, no manual install)

Using pip (manual install)

Tools (26 total — 20 unique + 6 aliases)

Resources

Prompts

Session Management

Agent Skill

Output Modes

Output Summarization

Cell Execution

Development

Architecture Overview

License

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Notebookllm?

Does Notebookllm need an API key?

What transport does Notebookllm use?

When was Notebookllm last checked?

Documentation

notebookllm

Key Features

Quick Start

Why notebookllm?

Installation

CLI Reference

notebookllm convert

notebookllm inspect

notebookllm search

notebookllm get

notebookllm tokens

notebookllm server

Python API

Loading and Saving

Converting to Optimized Text for Agents

Token Counting

Cell Operations

Search and Filter

Inspection

Validation

Supported Formats

MCP Server for AI Agent Integration

Setup

`notebookllm convert`

`notebookllm inspect`

`notebookllm search`

`notebookllm get`

`notebookllm tokens`

`notebookllm server`

`notebookllm convert`

`notebookllm inspect`

`notebookllm search`

`notebookllm get`

`notebookllm tokens`

`notebookllm server`