v2.0.0 — multilingual rewrite, async audio, MCP-spec descriptions

v2.0.0 unblocks v1.x and closes the full issue backlog. The selector / extraction / browser-lifecycle stack is rewritten end-to-end so the server stops breaking every time NotebookLM ships a UI tweak.

---

🔥 What this fixes

• ask_question works again. v1.x has been timing out since NotebookLM removed div.thinking-message. v2 replaces the selector-gated wait with streaming-stability detection — an answer is final when the extracted text is identical across N consecutive 750 ms polls. (closes #43)
• No more 100 % CPU loops. New src/browser/watchdog.ts: bounded poll counts, Node-side sleep fallback, periodic page.evaluate(() => true) health check. Wedged renderers surface a clear error instead of pegging a core. (closes #16)
• No more orphan Chrome processes. SIGTERM → 5 s → SIGKILL chain at shutdown. (closes #29)
• Browser launches on macOS Tahoe and Windows again. Auto-fallback to bundled Chromium when system Chrome refuses to start; force via BROWSER_CHANNEL=chromium. (closes #13, #19)
• Notebook library load no longer crashes. Safe accessors in src/library/metadata.ts for entries with missing topics/use_cases/content_types. (closes #33)
• Stdio is clean. Banner and all logs go to stderr; node dist/index.js < /dev/null produces 0 bytes on stdout. (closes #40)
• Better error message for unknown resource URIs — clients hitting mcp://notebooklm get pointed at notebooklm://library. (closes #15)

---

🚀 New capabilities

• add_source tool — paste URLs or text into a notebook from an agent. Returns sourceCountBefore/After so the call is verifiable. (closes #25)
• Audio Overview workflow — async by design: generate_audio returns immediately with status: "started" | "in_progress" | "ready", poll get_audio_status, then download_audio. Idempotent — existing tiles are detected. (closes #11, audio scope; Video / Slides / Quiz / Infographic tracked for a follow-up)
• Citations on ask_question — new source_format arg (none | inline | footnotes | json). DOM-level extraction populates a structured sources[] field. (closes #20)
• Streamable-HTTP transport — --transport http --port 3000 [--host 0.0.0.0]. Routes POST /mcp and GET /healthz, MCP-spec session-id header model. Built on the SDK's StreamableHTTPServerTransport (no Express). (closes #4, #7)
• Multi-account — --account <name> flag (or NOTEBOOKLM_ACCOUNT env). Each account gets an isolated Chrome profile under ~/.local/share/notebooklm-mcp/accounts/<name>/. No credential storage. (closes #2)
• Configurable answer timeout — ANSWER_TIMEOUT_MS env + per-call browser_options.timeout_ms. Default raised 120 s → 600 s. (closes #14, #27)
• Provenance + AI-generated marker — _provenance envelope on ask_question results, prefix on the answer text, configurable via NOTEBOOKLM_AI_MARKER and NOTEBOOKLM_AI_MARKER_PREFIX. Closes the host-agent trust-boundary gap for indirect prompt injection. (closes #42)
• FOLLOW_UP_REMINDER is opt-in now via NOTEBOOKLM_FOLLOW_UP_REMINDER=true (default off). The previous append tripped prompt-injection guards on safety-trained host agents. (closes #28)
• get_audio_status tool — non-blocking probe that returns ready | in_progress | not_started. Pair with async generate_audio and download_audio.

---

🏗️ Architecture rewrite

Selector registry — a single file Google can break

All NotebookLM-facing CSS / aria selectors live in src/notebooklm/selectors.ts. UI changes from Google now require touching exactly one file. Anchors are class- and [role="*"]-based with Material-Symbols icon names as fallbacks; the modal anchor is [role="dialog"] (race-free vs. the .mdc-dialog--open animation class). The registry covers EN, DE, FR, ES, PT, IT, NL and JA NotebookLM locales.

Browser lifecycle as its own module

• src/browser/browser-manager.ts owns launch / dispose, with profileStrategy: auto | single | isolated to fall back to an isolated per-instance profile when the base profile is locked
• src/browser/chromium-fallback.ts for the channel-failure → bundled-Chromium retry
• src/browser/watchdog.ts for the bounded-poll + health-check pattern reused across chat extraction, citation extraction, and source ingestion

Session recovery

findChatInput() recovery: 2× Escape → URL clean → reload — fixes ask_question failing after add_source or after a citation source-panel was left open.

Source ingestion (src/notebooklm/sources.ts)

• Robust dialog open: sidebar button → ?addSource=true URL fallback
• Snapshot count after fill, before submit
• UUID-redirect detection for pasted-text uploads
• Dual-anchor countSources() + 90 s post-submit poll with [role="alert"] error surfacing

MCP-spec compliance

• Server-level instructions string with cross-tool workflow guide — clients merge it into the system prompt automatically
• Tool descriptions condensed to what + when; annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint / title) on every tool

---

⚠️ Migration notes (v1 → v2)

• FOLLOW_UP_REMINDER is off by default. Set NOTEBOOKLM_FOLLOW_UP_REMINDER=true to keep the old append.
• answerTimeoutMs default raised 120 s → 600 s. Set ANSWER_TIMEOUT_MS=120000 to keep the old fail-fast ceiling.
• Answer text is now prefixed with the AI-generated marker by default. Set NOTEBOOKLM_AI_MARKER=false to disable (not recommended for host-agent safety).
• Resource URI scheme is notebooklm://…. Clients that built URLs starting with mcp:// need to update.
• v1 is no longer supported.

---

🧰 Tooling & DX

• ESLint flat config + Prettier; npm run lint, npm run format, npm run check (format-check + lint + build in one)
• Type-safe build with zero as any casts; DOM types enabled for in-page evaluations (lib: ["ES2022", "DOM", "DOM.Iterable"])
• Default viewport raised 1024×768 → 1920×1080 so NotebookLM doesn't drop into the mobile Studio layout
• add_source, generate_audio, download_audio, get_audio_status accept a show_browser flag for live debugging

📖 Docs

Full README rewrite plus refreshed docs/configuration.md, docs/tools.md, docs/troubleshooting.md, docs/usage-guide.md — covering install, client wiring (Claude Code, Cursor, Codex, generic), authentication, transports, multi-account, full tool list, profiles, citations, provenance, configuration, migration. WSL2 + WSLg is documented as supported; WSL1 is not. (closes #32, #8)

---

Stats: 47 files changed, 6 270 insertions(+), 1 712 deletions(−)

---

🙏 Acknowledgements

Several community PRs and reports shaped v2.0.0. Their ideas live on in the new code even where the final implementation took a different shape:

• @joaocarlos (#23) — diagnosed the 100 % CPU zombie-page loop and prototyped the bounded-poll + health-check pattern. Shipped as src/browser/watchdog.ts.
• @joaocarlos (#24) — DOM citation extraction. Shipped as source_format on ask_question + src/notebooklm/citations.ts.
• @Toryn02 (#44) — argued for an ANSWER_TIMEOUT_MS env var. Shipped exactly as proposed.
• @leo-dower (#37) — surfaced the prompt-injection-flag conflict around FOLLOW_UP_REMINDER. Shipped as opt-in (default off).
• @dave-007 (#41) — Studio artifact generation via direct batchexecute RPC. Audio Overview shipped via browser automation in v2.0.0; the RPC notes will guide the rest of the Studio surface in a follow-up.
• Plus every issue reporter whose precise repros made each fix traceable.

Thank you all 🙌

---

📦 Issue closeout — full v1 backlog cleared

Bugs fixed: #43 · #42 · #40 · #33 · #29 · #28 · #27 · #19 · #16 · #15 · #14 · [#13](https://gith...

v1.2.1 - Completions Capability Fix

Bug Fix

• Added missing completions: {} capability to server configuration (PR #10 by @joaocarlos)

This fixes the startup crash on Claude Desktop and other MCP clients:

Error: Server does not support completions (required for completion/complete)

Closes: #5, #6, #9, #12

Thanks to @joaocarlos for the fix!

v1.2.0 - Tool Profiles & LibreChat Fix

What's New

Tool Profiles System

Reduce token usage by loading only the tools you need:

• minimal (5 tools) - Query-only operations
• standard (10 tools) - + Library management
• full (16 tools) - All tools

CLI Configuration

npx notebooklm-mcp config get
npx notebooklm-mcp config set profile minimal
npx notebooklm-mcp config set disabled-tools "cleanup_data,re_auth"
npx notebooklm-mcp config reset

Environment variables: NOTEBOOKLM_PROFILE, NOTEBOOKLM_DISABLED_TOOLS

Bug Fixes

• LibreChat Compatibility - Fixed "Server does not support completions" error (#3)
• Thinking Detection - Fixed incomplete answers showing placeholder text

Improvements

• Modularized codebase for better maintainability
• Removed unreliable text-based placeholder detection

Full Changelog: See CHANGELOG.md

v1.1.2 - First Stable Release

NotebookLM MCP Server - First Stable Release

Let your CLI agents (Claude Code, Codex, Cursor) chat directly with NotebookLM for zero-hallucination answers based on your own notebooks.

This is the first stable release after thorough testing and feature refinement. The server is production-ready and actively used in real-world projects.

---

Installation

Quick Start

Claude Code:

claude mcp add notebooklm npx notebooklm-mcp@latest

Codex:

codex mcp add notebooklm -- npx notebooklm-mcp@latest

Cursor:
Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "notebooklm": {
      "command": "npx",
      "args": ["-y", "notebooklm-mcp@latest"]
    }
  }
}

See README for more installation options (Gemini, amp, VS Code).

---

What This Solves

When you tell Claude or Cursor to "search through my documentation", here's what happens:

• Massive token consumption: Reading multiple files repeatedly
• Inaccurate retrieval: Keyword search misses context and connections
• Hallucinations: Invents plausible-sounding APIs when it can't find something
• Expensive and slow: Each question requires re-reading files

Solution: Let your local agents chat directly with NotebookLM — Google's zero-hallucination knowledge base powered by Gemini 2.5 that provides intelligent, synthesized answers from your docs.

Your Task → Local Agent asks NotebookLM → Gemini synthesizes answer → Agent writes correct code

No more manual copy-paste between NotebookLM and your editor. Your agent asks NotebookLM directly and gets answers straight back in the CLI.

---

Core Features

Zero Hallucinations

NotebookLM refuses to answer if information isn't in your docs. No invented APIs.

Autonomous Research

Claude asks follow-up questions automatically, building complete understanding before coding.

Smart Library Management

Save NotebookLM links with tags and descriptions. Claude auto-selects the right notebook for your task.

Deep Cleanup Tool

Fresh start anytime. Scans entire system for NotebookLM data with categorized preview.

Persistent Sessions

Browser sessions stay alive across multiple queries for faster responses.

Human-Like Automation

Realistic typing speeds, natural delays, and mouse movements to avoid detection.

---

What's New in v1.1.2

Version History Overview

v1.1.x - Feature Additions:

• Added reference to companion Claude Code Skill version
• Fixed binary execution permissions across platforms
• Expanded installation guides (Cursor, Gemini, amp, VS Code)
• Major library management improvements

v1.0.x - Stability Refinements:

• Initial public release with core functionality
• Multiple bug fixes and documentation improvements
• Authentication flow hardening
• Browser automation reliability improvements

Full Changelog

v1.1.2 (Latest)

• Add Claude Code Skill reference to README
• Include package-lock.json in repository
• Clean up gitignore for CLAUDE.md

v1.1.1

• Fix binary permissions across npm installations
• Add postbuild script for executable setup

v1.1.0

• Major feature update with enhanced library management
• Improved session handling

v1.0.5

• Add installation guides for multiple clients (Cursor, Gemini, amp, VS Code)

v1.0.1 - v1.0.4

• Documentation improvements
• Authentication flow fixes
• Browser automation stability enhancements

v1.0.0

• Initial public release
• Core MCP server functionality
• Browser automation with Patchright
• Smart library management
• Deep cleanup tool

---

Quick Start Guide

1. Install the MCP server

See Installation section above for your specific client.

2. Authenticate (one-time)

Say in your chat:

"Log me in to NotebookLM"

A Chrome window opens → log in with Google → Done.

3. Create your knowledge base

Go to notebooklm.google.com:

• Create notebook
• Upload your docs (PDFs, Google Docs, markdown, websites, YouTube videos)
• Share: ⚙️ Share → Anyone with link → Copy

4. Let your agent use it

"I'm building with [library]. Here's my NotebookLM: [link]"

That's it. Your agent now asks NotebookLM whatever it needs, building expertise before writing code.

---

Real-World Example

Building an n8n Workflow Without Hallucinations

Challenge: n8n's API is new — Claude hallucinates node names and functions.

Solution:

1. Downloaded complete n8n documentation → merged into manageable chunks
2. Uploaded to NotebookLM
3. Told Claude: "Build me a Gmail spam filter workflow. Use this NotebookLM: [link]"

Watch the AI-to-AI conversation:

Claude → "How does Gmail integration work in n8n?"
NotebookLM → "Use Gmail Trigger with polling, or Gmail node with Get Many..."

Claude → "How to decode base64 email body?"
NotebookLM → "Body is base64url encoded in payload.parts, use Function node..."

Claude → "How to parse OpenAI response as JSON?"
NotebookLM → "Set responseFormat to json, use {{ $json.spam }} in IF node..."

Claude → "What about error handling if the API fails?"
NotebookLM → "Use Error Trigger node with Continue On Fail enabled..."

Claude → ✓ "Here's your complete workflow JSON..."

Result: Perfect workflow on first try. No debugging hallucinated APIs.

---

Why NotebookLM, Not Local RAG?

Approach	Token Cost	Setup Time	Hallucinations	Answer Quality
Feed docs to Claude	Very high	Instant	Yes - fills gaps	Variable retrieval
Web search	Medium	Instant	High - unreliable sources	Hit or miss
Local RAG	Medium-High	Hours	Medium - retrieval gaps	Depends on setup
NotebookLM MCP	Minimal	5 minutes	Zero - refuses if unknown	Expert synthesis

What Makes NotebookLM Superior

1. Pre-processed by Gemini: Upload docs once, get instant expert knowledge
2. Natural language Q&A: Not just retrieval — actual understanding and synthesis
3. Multi-source correlation: Connects information across 50+ documents
4. Citation-backed: Every answer includes source references
5. No infrastructure: No vector DBs, embeddings, or chunking strategies needed

---

Alternative: Claude Code Skill

Prefer Claude Code Skills over MCP? This server is now also available as a native Claude Code Skill:

NotebookLM Claude Code Skill - Clone to ~/.claude/skills and start using immediately

Key differences:

• MCP Server (this repo): Persistent sessions, works with Claude Code, Codex, Cursor, and other MCP clients
• Claude Code Skill: Simpler setup, Python-based, stateless queries, works only with Claude Code

Both use the same browser automation technology and provide zero-hallucination answers from your NotebookLM notebooks.

---

Documentation

• README - Complete overview and quick start
• Usage Guide - Patterns, workflows, tips
• Tool Reference - Complete MCP API
• Configuration - Environment variables
• Troubleshooting - Common issues

---

Technical Details

Requirements

• Node.js 18.0.0 or higher
• Chrome/Chromium browser (installed automatically if needed)
• Google account for NotebookLM access

Architecture

• TypeScript-based MCP server
• Browser automation via Patchright
• Persistent session management
• Local data storage via env-paths

Platform Support

• Linux
• macOS
• Windows

---

FAQ

Is it really zero hallucinations?
Yes. NotebookLM is specifically designed to only answer from uploaded sources. If it doesn't know, it says so.

What about rate limits?
Free tier has daily query limits per Google account. Quick account switching supported for continued research.

How secure is this?
Chrome runs locally. Your credentials never leave your machine. Use a dedicated Google account if concerned.

Can I see what's happening?
Yes. Say "Show me the browser" to watch the live NotebookLM conversation.

What makes this better than Claude's built-in knowledge?
Your docs are always current. No training cutoff. No hallucinations. Perfect for new libraries, internal APIs, or fast-moving projects.

---

Disclaimer

This tool automates browser interactions with NotebookLM to make your workflow more efficient. However, a few important notes:

About Browser Automation

While this server includes humanization features (realistic typing speeds, natural delays, mouse movements) to make automation behave naturally, I cannot guarantee Google won't detect or flag automated usage. I recommend using a dedicated Google account for automation rather than your primary account — think of it like web scraping: probably fine, but better safe than sorry.

About CLI Tools and AI Agents

CLI tools like Claude Code, Codex, and similar AI-powered assistants are incredibly powerful, but they can make mistakes. Please use them with care and awareness:

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

I built this tool for myself because I was tired of the copy-paste dance between NotebookLM and my editor. I'm sharing it in the hope it helps others too, but I cannot take responsibility for any issues, data loss, or account problems that might occur. Use at your own discretion an...