⚡ 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 , zero headaches. The legacy package is deprecated. Install to get everything.
Jupyter notebooks, made agent-ready. 8+ formats · MCP server · async execution · token budgeting.
星數
4
工具
—
可用率
—
pip install
notebookllm-mcp
notebookllm[mcp]
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.
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
# 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.
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