notebooklm-assistant

name	notebooklm-assistant
description	This skill provides expertise for working with Google NotebookLM via the notebooklm MCP server. Use when the user says "NotebookLM", "notebook", "create a notebook", "add sources to notebook", "query my notebook", "generate audio overview", "make a podcast", "create flashcards", "research this topic", "studio artifact", "notebook sources", "cross-notebook query", or any request involving NotebookLM features. Also trigger when the user wants to create study materials, AI-generated audio discussions, slide decks, quizzes, mind maps, infographics, or reports from their notebook sources.
version	0.2.0

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.