notebooklm-mcp

> Unofficial project — good to know before you start

>

> This is not affiliated with Google. It talks to the same `batchexecute`

> endpoints the NotebookLM web app uses, with a browser fallback when they move.

> They are undocumented, so they can change without notice — when that happens we

> ship a fix, as we have for every change so far.

>

> Two practical notes: use a dedicated Google account for automation, and

> expect NotebookLM's own quotas to apply at high volume. See

> Disclaimer for the full text.

What You Can Build

🔗 No-code automation pipelines — The 33-endpoint REST API means NotebookLM becomes a step in n8n, Zapier, Make, or a plain `curl` in cron. No agent, no MCP client, no Node in your stack — just HTTP. This is the half most NotebookLM libraries don't have.

🤖 Agent tooling — The same engine over MCP for Claude Code, Cursor and Codex, with a bundled skill that primes the agent on citation formats, the daily-quota-aware batch pattern, and transport selection.

📚 Research at volume — Multi-account rotation with automatic re-authentication, built for overnight runs of 1 000+ questions across several notebooks without babysitting.

🎙️ Full Studio generation — Audio overviews, video, infographics, reports, presentations, data tables, plus flashcards, quizzes and mind maps — generated and downloaded programmatically.

Use Cases & Recipes

NotebookLM is a grounded engine: Gemini reads your sources and answers _from them_, with citations. The winning pattern is to let it do the expensive reading while your own stack handles orchestration and the last mile.

Spend fewer tokens — offload the reading

• 🪙 Zero-token synthesis layer — Drop 30 documents in a notebook, let Gemini do the heavy analysis, and spend your agent's context only on the final polish. The reasoning happens server-side; your agent just orchestrates (`add_notebook` → `source_add` → `notebook_ask`).
• 💾 Answer cache you can re-read offline — `vault_batch` writes every answer to disk as structured JSON against a published schema, so a batch run becomes a corpus you can grep, diff, re-index, or feed to a retrieval layer — without re-querying and re-spending quota.

Wire it into things that aren't agents

• ⚙️ NotebookLM as an n8n / Zapier / Make step — Because it speaks plain HTTP, a citation-backed answer becomes one node in a workflow: a form submission triggers a question, the cited answer lands in a sheet, a Slack message, or a database. No agent runtime involved.
• 📄 Document intake pipeline — Watch a folder or an inbox, push new PDFs and URLs in as sources, and ask a standing set of questions against them on every arrival.

Grounded answers with a paper trail

• 🔍 Citations with the actual source text — Answers come back with source names _and the quoted excerpts_ they rest on, extracted from the citation panel — so a claim can be checked, not just attributed.
• 🎓 Literature review at thesis scale — Batch 100+ research questions across multiple notebooks, rotate accounts as daily quotas run out, and resume where it stopped. Built for, and tested on, exactly this.

Get artifacts back out

• 🔁 One source set, every format — Fan a single notebook out to a podcast, a video, a slide deck, a report, a quiz and a mind map, then download them all locally.

In the Wild

Real deployments, not hypotheticals.

• 📚 A doctoral literature review at batch scale — The project was built for, and is

continuously tested on, overnight runs of 1 000+ research questions spread across

several notebooks: multi-account rotation picks up when a daily quota runs out, every

answer is written to disk with its citations, and an interrupted run resumes instead of

starting over. The batch pattern in `vault_batch` exists because a thesis

needed it.

• 🔌 Replacing a RAG engine with the REST API — `musnymubarak/Calim_Doc`

swapped a Gemini-based retrieval engine for this project's HTTP API, running it as a

Docker service (`notebooklm:3000`) behind a full client and worker layer. A good

illustration of the REST half: no agent runtime, no MCP client — NotebookLM simply

became a backend service their Python app calls.

Built something with it? Open an issue — this section is for other people's work.

Features

Q&A with Citations

• Ask questions to NotebookLM and get accurate, citation-backed answers
• Source citation extraction with 5 formats: none, inline, footnotes, json, expanded (97% excerpt success rate)
• Session management for multi-turn conversations with auto-reauth on session expiry

Content Generation

Generate multiple content types from your notebook sources:

Video Visual Styles: classroom, documentary, animated, corporate, cinematic, minimalist

Language of generated content: pass `language` to any generator — a BCP-47 code (`es`, `ja`, `pt_BR`, `zh_Hans`) or a name in English or in the language itself (`"Spanish"`, `"Español"`). 81 languages are accepted, and an unrecognised one is refused rather than quietly swapped for another. Set a default with `NOTEBOOKLM_CONTENT_LANGUAGE`; it is deliberately independent of `NOTEBOOKLM_UI_LOCALE`, which only picks the interface language the browser fallback reads.

Flashcards and quizzes are generated via `generate_study_aid`; mind maps via `generate_mind_map`. v3 also adds `share_notebook`, `manage_labels`, and `research_sources` (web/Drive source discovery) — see the changelog.

Content Download

• Download Audio — WAV audio files
• Download Video — MP4 video files
• Download Infographic — PNG image files
• Text-based content (report, presentation, data_table) is returned in the API response
• Delete generated content (`content_delete`) — until now a notebook accumulated every draft anyone ever asked for, with no way to remove one short of the web UI

Source Management

• Add sources: Files (PDF, TXT, DOCX), URLs, Text, YouTube videos, Google Drive
• List sources: Every source with its ID and title (`source_list`)
• Read a source in full (`source_read`): the exact text NotebookLM indexed — what it actually reasons over, which the web UI only shows in fragments. Quote a source verbatim, check what a PDF really yielded, or hand the raw material to another tool. Name the source instead of its ID if you prefer; an ambiguous name is refused rather than guessed. Long sources arrive one page at a time, with an explicit instruction for fetching the next — or `paginate: false` for the whole document at once.

Notebook Library

• Multi-notebook management with validation and smart selection
• Auto-discovery: Automatically generate metadata via NotebookLM queries
• Search notebooks by keyword in name, description, or topics
• Scrape notebooks: List all notebooks from NotebookLM with IDs and names
• Bulk delete: Delete multiple notebooks at once

Accounts & Localization

• Personal _and_ Google Workspace accounts — recognizes both NotebookLM hosts (`notebooklm.google.com` and the `notebook.google.com` Workspace alias), so Workspace sessions authenticate cleanly instead of looping on "session expired"
• UI-language-aware — drives NotebookLM whether its interface is in English, French, German, or Japanese (`en` · `fr` · `de` · `ja`); add a language in a single JSON file

Integration Options

• MCP Protocol — Claude Code, Cursor, Codex, any MCP client
• Agent Skill — ships a bundled `notebooklm` skill (also standalone: `roomi-fields/notebooklm-skill`) that teaches the agent citation formats, the daily-quota-aware batch pattern, and when to use which transport
• HTTP REST API — n8n, Zapier, Make.com, custom integrations
• Docker — Isolated deployment with Docker or Docker Compose
• **RTFM retrieval layer** — `/batch-to-vault` writes citation-backed answers as markdown + JSON sidecars (`nblm-answer-v1` schema), indexable by RTFM (FTS5 + semantic) for unlimited offline queries. Ideal for academic / SOTA workflows. Guide.

Quick Start

Option 0 — Claude Code marketplace (one-liner, recommended for Claude Code users)

The fastest way to get NotebookLM into Claude Code. Distributed via the `roomi-fields/claude-plugins` marketplace alongside RTFM (the retrieval companion — see RTFM integration guide):

/plugin marketplace add roomi-fields/claude-plugins
/plugin install notebooklm@roomi-fields

That registers the MCP server, runs `npx -y @roomi-fields/notebooklm-mcp@` automatically (Node ≥ 18 required), and lets you upgrade with two commands when a new release ships: `/plugin marketplace update roomi-fields` then `/reload-plugins`. Then run `npx -y -p @roomi-fields/notebooklm-mcp notebooklm-mcp-setup-auth` once in a terminal to log into Google (a visible Chrome opens). To install RTFM at the same time: `/plugin install rtfm@roomi-fields`.

Option 1 — HTTP REST API (n8n, Zapier, Make, curl, any HTTP client)

git clone https://github.com/roomi-fields/notebooklm-mcp.git
cd notebooklm-mcp
npm install && npm run build
npm run setup-auth   # One-time Google login
npm run start:http   # Start REST API on port 3000

# Citation-backed Q&A, single curl, JSON response
curl -X POST http://localhost:3000/ask \
  -H 'Content-Type: application/json' \
  -d '{"question": "Summarize chapter 3", "notebook_id": "your-id", "source_format": "json"}'

The full surface is 33 documented endpoints — see the REST API reference. For overnight batches of 1 000+ questions, see the batch pattern.

Option 2 — MCP Mode (Claude Code, Cursor, Codex)

# Build (same package, MCP transport)
git clone https://github.com/roomi-fields/notebooklm-mcp.git
cd notebooklm-mcp
npm install && npm run build

# Claude Code
claude mcp add notebooklm node /path/to/notebooklm-mcp/dist/index.js

# Cursor — add to ~/.cursor/mcp.json
{
  "mcpServers": {
    "notebooklm": {
      "command": "node",
      "args": ["/path/to/notebooklm-mcp/dist/index.js"]
    }
  }
}

Log in once — in a terminal, not through the assistant. Run the interactive

Google login as a command; a visible Chrome window opens, you sign in, and the

saved session is then reused by the MCP server:

npm run setup-auth          # from a clone (Option 2 above)
notebooklm-mcp setup-auth   # from a global install (npm i -g @roomi-fields/notebooklm-mcp)

Do the login in a terminal rather than by asking the assistant _"log me in"_:

some stdio MCP clients (e.g. Claude Desktop) cap tool-call duration and cut off

the up-to-10-minute interactive login before you can finish signing in (see

issue #27).

Option 3 — Docker (NAS, server, headless)

# Build and run
docker build -t notebooklm-mcp .
docker run -d --name notebooklm-mcp -p 3000:3000 -p 6080:6080 -v notebooklm-data:/data notebooklm-mcp

# Authenticate via noVNC
# 1. Open http://localhost:6080/vnc.html
# 2. Run: curl -X POST http://localhost:3000/setup-auth -d '{"show_browser":true}'
# 3. Login to Google in the VNC window

See Docker Guide for NAS deployment (Synology, QNAP).

Documentation

Full docs site: **** · OpenAPI 3.1 spec

Roadmap

See ROADMAP.md for planned features and version history.

Latest releases:

• v3.0.1 — Interactive Google login as a first-class CLI command (`notebooklm-mcp setup-auth`) for global / stdio-client installs; `setup_auth` / `re_auth` accept a top-level `headless` (#27)
• v3.0.0 — Major refactor: dual transport (NotebookLM's internal `batchexecute` RPC API with automatic DOM fallback), 10-100× faster and immune to UI rebrands; 5 new tools (notebook sharing, study aids, mind maps, source labels, web research)
• v2.3.0 — Full support for Google's "Gemini Notebook" rebrand: create / list / rename / delete, sources, and every Studio generation type re-verified end-to-end (#23, #21)
• v2.2.1 — Recognize both NotebookLM hosts so Google Workspace accounts authenticate (the `notebook.google.com` alias); notebook listing no longer wastes ~30s after the "Gemini Notebook" rebrand; HTTP banner reads the real version. Diagnosis + patch by @kpietkaa (#19)
• v2.2.0 — Fix new-answer detection timing out when an answer repeats an earlier one (position-based identity, not text-hash); graceful shutdown on stdio disconnect; Japanese UI locale
• v2.1.1 — Thai UI selectors for `notebook_create` (partial, #18)
• v2.1.0 — `note_list` and `note_get` MCP tools (#17)
• v2.0.4 — German UI selectors (closes #14)
• v2.0.0 — Tools renamed to a namespaced tree (`notebook_ask`, `source_add`, `session_list`, `server_health`, `vault_batch`…) across 9 namespaces; `tools/list` advertises only the canonical names. Backward compatible — the legacy flat names still work as aliases, so existing scripts and configs keep running. Also adds MCP `annotations` (read-only / destructive / idempotent / open-world hints) and `outputSchema` + `structuredContent` on every tool. Published on the Smithery registry.
• v1.7.0 — `batch_to_vault` exposed as a first-class MCP tool (parity with the HTTP endpoint, no localhost server required); shared `runBatchToVault` helper deduplicates the loop across both transports
• v1.6.0 — `/batch-to-vault` endpoint + RTFM integration (`nblm-answer-v1` JSON Schema published at schemas.roomi-fields.com/nblm-answer-v1.json) for caching NotebookLM answers as a searchable markdown vault
• v1.5.8 — NotebookLM 2026 UI adaptations (icon-label sanitization, Discussion-panel recovery, count-based source detection) — PR #5 by @KhizarJamshaidIqbal
• v1.5.7 — Citation extraction selector fix (`.highlighted`) and Docker multi-stage build — PR #1 by @JulienCANTONI
• v1.5.6 — Citation extraction major rewrite (97% success rate), browser-verified auth at startup, profile auto-sync
• v1.5.0 — Complete Studio content generation (video, infographic, presentation, data_table) + Notes management + Delete sources
• v1.4.0 — Content management (sources, audio, generation) + Multi-account

_Intermediate patch and hardening releases (1.5.x–1.7.x) are in the full CHANGELOG._

Not yet implemented:

• Discover sources (Web/Drive search with Fast/Deep modes)
• Edit notes (create, delete, and convert are implemented)

Disclaimer

This tool automates browser interactions with NotebookLM. Use a dedicated Google account for automation. CLI tools like Claude Code can make mistakes — always review changes before deploying.

See full Disclaimer below.

Contributing

Found a bug? Have an idea? Open an issue or submit a PR!

See CONTRIBUTING.md for guidelines.

License

MIT — Use freely in your projects. See LICENSE.

Author

Romain Peyrichou — @roomi-fields

Acknowledgments

Thanks to everyone who has contributed code, ideas, and bug reports:

• Khizar Jamshaid Iqbal — @KhizarJamshaidIqbal, 2025 UI selector fixes, doctor script, PII scrub
• Kazik Pietka — @kpietkaa, `notebook.google.com` rebrand support
• Rui Ruiberriz — @Excauboi, `hl=` on app URLs + click-through scrape fallback
• **@he0xwhale** — `note_list` / `note_get` MCP tools
• **@eminsnow** — canonical tool names (`_` over `.`)
• Julien Cantoni — @JulienCANTONI

Full Disclaimer

About browser automation:

While I've built in humanization features (realistic typing speeds, natural delays, mouse movements), I can't guarantee Google won't detect or flag automated usage. Use a dedicated Google account for automation.

About CLI tools and AI agents:

CLI tools like Claude Code, Codex, and similar AI-powered assistants are powerful but can make mistakes:

• Always review changes before committing or deploying
• Test in safe environments first
• Keep backups of important work
• AI agents are assistants, not infallible oracles

I built this tool for myself and share it hoping it helps others, but I can't take responsibility for any issues that might occur. Use at your own discretion.