notebooklm-assistant

NotebookLM Assistant

Guide for using the NotebookLM MCP server tools. The server exposes 39 tools across notebooks, sources, chat, research, studio artifacts, sharing, and more.

Updated for notebooklm-mcp-cli v0.7.7 (June 19, 2026). See "What's new in v0.7.x" below.

What's new in v0.7.x (since the v0.7.1 docs)

• Research auto-import [v0.7.4]. research_status(..., auto_import=True) imports discovered sources into the notebook on completion, so you no longer get an empty notebook shell. With auto_import=False (default) the response carries a next_action hint giving the exact research_import call to run. Deep-research polling default raised to 15 minutes (max_wait=900).
• Faster Drive listing [v0.7.6 / v0.7.4]. source_list_drive(..., skip_freshness=True) skips the per-source freshness API call on large notebooks. Freshness checks that do run are now parallelized (8 workers) and degrade gracefully (stale: null) on a single-source failure.
• Reliable source content right after add [v0.7.2]. source_get_content now polls NotebookLM indexing states with backoff, so reads immediately after source_add succeed instead of returning a processing/empty result.
• Studio fast-track + cinematic video [v0.7.0]. Agents infer format, style, and prompt and generate immediately; guided preview is reserved for vague or high-stakes requests. video_format=cinematic is supported (drive it through focus_prompt).
• Auth health checks [v0.7.0–v0.7.2]. Multi-probe health checker distinguishes stale (truly expired, re-auth) from unverified (transient network blip, do not re-auth). server_info, refresh_auth, and studio_create now share one auth gate, so they no longer disagree on semi-stale sessions. Result is cached 30s.
• RPC resilience [v0.7.4]. NOTEBOOKLM_RPC_OVERRIDES env var, RPCDriftError on RPC rotation, and backoff retry on throttling. Restart the server after setting overrides.
• SOCKS proxy support [v0.7.7]. ALL_PROXY with socks5 / socks5h works (the new socksio dependency). A remote MCP deployment guide was added for Claude web/mobile connectors.
• Reverted, do not use: the v0.7.2 ChatGPT file/artifact bridges and the /artifacts/{filename} route were rolled back in v0.7.3 for an SSRF and disk-leak issue.

Authentication

Before any operation, confirm auth is working. If tools fail with auth errors:

1. Call refresh_auth() to reload cached credentials.
2. If that fails, the user needs to provide fresh browser cookies via save_auth_tokens(cookies="..."), or run nlm login in a terminal.
3. Cookies come from Chrome DevTools → Network tab → any request to notebooklm.google.com → copy the Cookie header value.
4. Five cookies are required: SID, HSID, SSID, APISID, SAPISID.
5. Tokens are valid for 2-4 weeks before needing refresh.

Reading auth status (v0.7.0+). nlm login --check and server_info run a multi-probe health check and return one of five stable states. Treat them differently:

• stale means credentials are genuinely expired or the profile failed to load. Re-auth.
• unverified means the check hit a transient network error. Do NOT prompt re-auth; retry shortly.

The check is cached for 30 seconds. refresh_auth() reloads tokens from disk; it cannot revive genuinely expired credentials, so an expired session still needs nlm login or fresh cookies.

Core Workflow Patterns

Creating and Populating a Notebook

1. notebook_create(title="Project Research")
2. Add sources with source_add():
   • URLs: source_add(notebook_id, source_type="url", url="https://...")
   • Text: source_add(notebook_id, source_type="text", text="...", title="My Notes")
   • Files: source_add(notebook_id, source_type="file", file_path="/path/to/doc.pdf")
   • Google Drive: source_add(notebook_id, source_type="drive", document_id="...")
   • Bulk URLs: source_add(notebook_id, source_type="url", urls="url1,url2,url3")
3. Wait for processing if needed: set wait=True on source_add. Reading content right after add is safe now; source_get_content polls indexing states with backoff (v0.7.2).

Querying Notebooks

• Simple query: notebook_query(notebook_id, query="What are the key findings?")
• Filter by sources: notebook_query(notebook_id, query="...", source_ids="id1,id2")
• Follow-up: reuse conversation_id from previous response.
• Large notebooks (50+ sources): use notebook_query_start(...) then poll notebook_query_status(query_id) to avoid MCP client timeouts.
• Cross-notebook: cross_notebook_query(query="...", all=True) searches everything.

Research (Web/Drive Discovery)

1. research_start(query="...", source="web", mode="fast") — starts async task.
2. research_status(notebook_id, task_id="...", auto_import=True) — poll until complete. With auto_import=True the sources land in the notebook automatically. With the default auto_import=False, read the next_action hint and call research_import yourself.
3. research_import(notebook_id, task_id, source_indices="0,1,2") — manual import path.

Modes: fast (~30s) or deep (~5min). Sources: web or drive. Deep runs can poll up to 15 minutes by default (max_wait=900).

Studio Artifacts (9 Types)

Create rich outputs from notebook sources. Always pass confirm=True.

Type	Key Options
audio	format: deep_dive, brief, critique, debate / length: long, medium, short
video	format: explainer, brief, cinematic / style presets (style does not apply to cinematic)
infographic	orientation + detail level
slide_deck	format: detailed, presenter
report	type: briefing, study_guide, blog_post
flashcards	difficulty: easy, medium, difficult
quiz	quiz_count: number of questions
data_table	data_table_description for guidance
mind_map	auto-organized from sources

Common options for all: language, focus_prompt, source_ids.

Fast-track behavior (v0.7.0). Infer format, style, and prompt from context and generate immediately with a one-line notice. Show a guided preview (settings plus the full prompt) only for vague requests, high-stakes output such as cinematic video, or when the user asks to review. For video_format=cinematic, pass the full creative brief through focus_prompt.

After creation, check with studio_status(notebook_id). Download with download_artifact(notebook_id, artifact_type, output_path).

Downloading & Exporting

• download_artifact(notebook_id, artifact_type="audio", output_path="./podcast.wav")
• Formats: quiz/flashcards support "json", "markdown", "html"; slide_deck supports "pdf", "pptx".
• export_artifact(notebook_id, artifact_id, export_type="docs") — exports to Google Docs/Sheets.

Tool Quick Reference

For full parameter details on all 39 tools, read references/tools-complete.md.

Notebook Management

• notebook_list() / notebook_get(id) / notebook_describe(id)
• notebook_create(title) / notebook_rename(id, new_title) / notebook_delete(id, confirm=True)

Source Management

• source_add(notebook_id, source_type, ...) — unified add (url/text/drive/file)
• source_list_drive(notebook_id, skip_freshness=False) — list with Drive freshness; pass skip_freshness=True on large notebooks to skip per-source freshness calls
• source_sync_drive(source_ids, confirm=True) — refresh stale Drive sources
• source_rename(notebook_id, source_id, new_title)
• source_delete(notebook_id, source_id, confirm=True)
• source_describe(source_id) — AI summary + keywords
• source_get_content(source_id) — raw indexed text (polls indexing states)

Chat & Query

• notebook_query(notebook_id, query, ...) — AI query with citations
• notebook_query_start(notebook_id, query, ...) / notebook_query_status(query_id) — async pair for 50+ source notebooks
• chat_configure(notebook_id, goal, custom_prompt, response_length)

Research

• research_start(query, source, mode) / research_status(notebook_id, ..., auto_import) / research_import(notebook_id, task_id, source_indices)

Notes

• note(notebook_id, action="create|list|update|delete", ...)

Sharing

• notebook_share_status(notebook_id)
• notebook_share_public(notebook_id, public=True|False)
• notebook_share_invite(notebook_id, email, role="viewer|editor")

Tags & Organization

• tag(action="add|remove|list|select", ...)

Batch & Pipeline

• batch(action="query|add_source|create|delete|studio", ...)
• pipeline(action="run|list", ...)

Safety Rules

Destructive operations require confirm=True:

• notebook_delete, source_delete, studio_delete, note(action="delete")
• source_sync_drive, notebook_share_batch, batch(action="delete")

Always confirm with the user before running destructive operations.

Rate Limits & Constraints

• Free tier: ~50 queries/day (API-enforced)
• Query timeout: 120s default; research polling up to 900s (15 min) for deep runs
• Custom prompt max: 10,000 characters
• Tokens valid: 2-4 weeks
• Uses undocumented Google APIs — may change without notice. If Google rotates RPC IDs, set NOTEBOOKLM_RPC_OVERRIDES and restart the server; watch for RPCDriftError.
• Behind a SOCKS proxy, ALL_PROXY with socks5/socks5h is supported (v0.7.7).
• For Claude web/mobile connector deployments, see the package's remote MCP deployment guide.