┌──────────────────────────────────────────────────────────────────────────────────┐
│                          NOTEBOOKLM RESEARCH AGENT                              │
├──────────────┬──────────────┬─────────────────┬─────────────────────────────────┤
│  Phase 1     │  Phase 2     │   Phase 3       │    Phase 4                      │
│  INGEST      │  SYNTHESIZE  │   CREATE        │    PUBLISH (optional)           │
│              │              │                 │                                 │
│ Sources:     │ Chat:        │ Claude writes:  │ threads-viral-agent:            │
│  URL         │  ask()       │  Articles ────→ │  → Threads                      │
│  Text        │  → cited     │  Social posts → │  → Instagram                    │
│  PDF/DOCX    │    answers   │  Newsletters  → │  → Facebook                     │
│  YouTube     │  → follow-up │  Reports ─────→ │                                 │
│  Google Drive│  → citations │                 │ Direct output:                  │
│  File upload │              │ trend-pulse     │  → Markdown file                │
│              │ Artifacts    │  → topic ideas  │  → JSON data                    │
│ Research:    │ (9 types):   │                 │  → Newsletter draft             │
│  web (fast)  │  audio       │ NotebookLM      │  → Podcast MP4                  │
│  web (deep)  │  video       │ artifacts used  │  → Video MP4                    │
│  drive       │  cinematic*  │ directly:       │  → Slide deck PDF               │
│              │  slide_deck  │  → Podcast      │  → Quiz / Flashcards            │
│ Auto-import  │  report      │  → Report       │                                 │
│ discovered   │  quiz        │  → Data table   │                                 │
│ sources      │  flashcards  │  → Infographic   │                                 │
│              │  mind_map    │                 │ * cinematic = Veo 3,            │
│              │  infographic │                 │   AI Ultra only                 │
│              │  data_table  │                 │                                 │
│              │  study_guide │                 │                                 │
└──────────────┴──────────────┴─────────────────┴─────────────────────────────────┘

8 Sub-APIs (notebooklm-py v0.3.4)

| Sub-API | Accessor | Description | |---|---|---| | Notebooks | client.notebooks | Create, list, get, delete, rename, describe, share | | Sources | client.sources | Add URL/text/file/Drive, list, delete, rename, refresh, guide, fulltext, wait | | Artifacts | client.artifacts | Generate 9 downloadable types, poll status, download, list, delete, rename, revise slides | | Chat | client.chat | Ask with citations, follow-up, conversation history, configure persona | | Research | client.research | Web/Drive research, poll results, import discovered sources | | Notes | client.notes | Create, list, update, delete text notes and mind maps | | Settings | client.settings | User settings (output language) | | Sharing | client.sharing | Public links, user permissions, view levels |

Phase 1: INGEST -- Source Collection

Create a notebook and populate it with sources. NotebookLM accepts 8 source types: URLs, text, PDF, DOCX, Markdown, CSV, YouTube, and Google Drive documents.

Create Notebook and Add Sources

Built-in CLI (notebooklm-py):

# Create a notebook
notebooklm notebook create "AI Agents Research"

# Add sources
notebooklm source add NOTEBOOK_ID --url "https://arxiv.org/abs/2401.12345"
notebooklm source add NOTEBOOK_ID --url "https://youtube.com/watch?v=VIDEO_ID"
notebooklm source add NOTEBOOK_ID --text "Custom Notes" --content "Full text here..."
notebooklm source add NOTEBOOK_ID --file /path/to/document.pdf

Our wrapper CLI (global command or scripts/notebooklm_client.py):

# After pip install ., use global commands:
# notebooklm-skill create --title "AI Agents Research" --sources url1 url2

# Or use scripts directly:
python3 scripts/notebooklm_client.py create \
  --title "AI Agents Research" \
  --sources \
    "https://arxiv.org/abs/2401.12345" \
    "https://blog.example.com/ai-agents-2026"

# Add more sources to existing notebook
python3 scripts/notebooklm_client.py add-source \
  --notebook NOTEBOOK_ID \
  --url "https://another-source.com/article"

# Add text source (pasted content)
python3 scripts/notebooklm_client.py add-source \
  --notebook NOTEBOOK_ID \
  --text "Full text content here..." \
  --text-title "Title of Source"

# Add file (PDF, Markdown, DOCX, CSV)
python3 scripts/notebooklm_client.py add-source \
  --notebook NOTEBOOK_ID \
  --file "/path/to/document.pdf"

# Add YouTube video (auto-extracts transcript)
python3 scripts/notebooklm_client.py add-source \
  --notebook NOTEBOOK_ID \
  --url "https://youtube.com/watch?v=VIDEO_ID"

# Add Google Drive document
python3 scripts/notebooklm_client.py add-source \
  --notebook NOTEBOOK_ID \
  --drive-id "DRIVE_FILE_ID" \
  --drive-title "Document Title"

Deep Web Research (auto-discover sources)

NotebookLM can search the web or Google Drive and auto-import relevant sources. This is one of the most powerful features -- it finds sources you did not know existed.

Built-in CLI:

notebooklm research start NOTEBOOK_ID "latest advances in AI agents"
notebooklm research poll NOTEBOOK_ID

Our wrapper CLI:

# Fast web research (quick scan, returns URLs)
python3 scripts/notebooklm_client.py research \
  --notebook NOTEBOOK_ID \
  --query "latest advances in AI agents" \
  --source web \
  --mode fast

# Deep web research (thorough analysis, returns report + URLs)
python3 scripts/notebooklm_client.py research \
  --notebook NOTEBOOK_ID \
  --query "comparison of agent frameworks" \
  --source web \
  --mode deep

# Google Drive research
python3 scripts/notebooklm_client.py research \
  --notebook NOTEBOOK_ID \
  --query "project notes on agent design" \
  --source drive

# Poll results and auto-import top discovered sources
python3 scripts/notebooklm_client.py research-poll \
  --notebook NOTEBOOK_ID \
  --import-top 5

Research modes:

| Mode | Speed | Output | Best For | |---|---|---|---| | fast | 10-30 sec | URL list + brief summary | Quick source discovery | | deep | 1-5 min | Full research report (Markdown) + URLs | Thorough analysis, complex topics |

Deep research returns a comprehensive Markdown report synthesizing findings across all discovered sources -- usable as-is or as input for Claude.

Source Types Reference

| Type | Method | CLI Flag | Notes | |---|---|---|---| | Web URL | add_url(url) | --url | Any web page, auto-indexes content | | YouTube | add_url(youtube_url) | --url | Auto-detects YouTube, extracts transcript | | PDF | add_file(path) | --file | Resumable upload, large files OK | | DOCX | add_file(path) | --file | Word documents | | Markdown | add_file(path) | --file | .md files | | CSV | add_file(path) | --file | Spreadsheet data | | Text | add_text(title, content) | --text --content | Pasted/copied content | | Google Docs | add_drive(file_id, title) | --drive-id --drive-title | Requires Drive access | | Google Slides | add_drive(file_id, title, mime) | --drive-id --drive-title | Presentation content | | Google Sheets | add_drive(file_id, title, mime) | --drive-id --drive-title | Spreadsheet data | | Image | add_file(path) | --file | Image content (OCR) |

Source Limits and Wait Behavior

• Max 50 sources per notebook
• Sources require processing time (5-60 seconds depending on size/type)
• Use --wait flag to block until source is ready
• Use wait_for_sources() for batch operations
• Source statuses: 1=processing, 2=ready, 3=error, 4=preparing

Python API (for custom scripts)

from notebooklm import NotebookLMClient

async with await NotebookLMClient.from_storage() as client:
    # Create notebook
    nb = await client.notebooks.create("AI Research")

    # Add sources
    src1 = await client.sources.add_url(nb.id, "https://example.com", wait=True)
    src2 = await client.sources.add_text(nb.id, "Notes", "Content...", wait=True)
    src3 = await client.sources.add_file(nb.id, "/path/to/doc.pdf", wait=True)

    # Deep web research
    task = await client.research.start(nb.id, "AI agents 2026", mode="deep")
    results = await client.research.poll(nb.id)  # Poll until complete
    imported = await client.research.import_sources(nb.id, task["task_id"], results["sources"][:5])

Phase 2: SYNTHESIZE -- Research & Analysis

Once sources are ingested, use NotebookLM to extract knowledge through cited Q&A and generate 9 types of downloadable native artifacts.

Ask Questions (Cited Answers)

Every answer includes source citations with exact passage references.

Built-in CLI:

notebooklm chat NOTEBOOK_ID "What are the key differences between ReAct and Reflexion?"
notebooklm chat NOTEBOOK_ID "Can you elaborate on point 3?" --conversation CONV_ID

Our wrapper CLI:

# Ask a question -- answer includes source citations
python3 scripts/notebooklm_client.py ask \
  --notebook NOTEBOOK_ID \
  --query "What are the key differences between ReAct and Reflexion agents?"

# Ask with specific sources only
python3 scripts/notebooklm_client.py ask \
  --notebook NOTEBOOK_ID \
  --query "Summarize the main findings" \
  --sources SOURCE_ID_1 SOURCE_ID_2

# Follow-up question (maintains conversation context)
python3 scripts/notebooklm_client.py ask \
  --notebook NOTEBOOK_ID \
  --query "Can you elaborate on point 3?" \
  --conversation CONVERSATION_ID

Chat Configuration

NotebookLM's chat can be configured for different interaction styles:

| Mode | Description | Use Case | |---|---|---| | default | Balanced answers | General research | | learning_guide | Socratic, asks follow-up questions | Study, learning | | concise | Short, direct answers | Quick lookups | | detailed | Thorough, comprehensive answers | Deep analysis |

Python API:

from notebooklm.models import ChatMode, ChatResponseLength

await client.chat.set_mode(nb.id, ChatMode.LEARNING_GUIDE)
await client.chat.configure(nb.id, response_length=ChatResponseLength.LONGER)

Generate Artifacts (10 Types)

NotebookLM natively generates 9 downloadable artifact types from ingested sources. These are generated server-side by Google -- no LLM cost on our end.

Warning: infographic generation works but download is unreliable (fragile API structure parsing). Use slides instead for downloadable visual content.

Built-in CLI:

notebooklm generate audio NOTEBOOK_ID
notebooklm generate video NOTEBOOK_ID
notebooklm generate report NOTEBOOK_ID --format briefing_doc
notebooklm generate quiz NOTEBOOK_ID
notebooklm generate flashcards NOTEBOOK_ID
# notebooklm generate infographic NOTEBOOK_ID  # ⚠️ download unreliable
notebooklm generate slide-deck NOTEBOOK_ID
notebooklm generate data-table NOTEBOOK_ID
notebooklm generate mind-map NOTEBOOK_ID

Our wrapper CLI:

# 1. Audio Overview (podcast-style discussion)
python3 scripts/notebooklm_client.py generate audio \
  --notebook NOTEBOOK_ID \
  --language en \
  --format deep_dive \
  --length default \
  --instructions "Focus on practical implications"

# 2. Video Overview
python3 scripts/notebooklm_client.py generate video \
  --notebook NOTEBOOK_ID \
  --format explainer \
  --style whiteboard

# 3. Cinematic Video (Veo 3, requires AI Ultra subscription)
python3 scripts/notebooklm_client.py generate cinematic-video \
  --notebook NOTEBOOK_ID \
  --instructions "Dramatic visual storytelling"

# 4. Slide Deck
python3 scripts/notebooklm_client.py generate slide-deck \
  --notebook NOTEBOOK_ID \
  --format detailed_deck

# 5. Report (Briefing Doc / Study Guide / Blog Post / Custom)
python3 scripts/notebooklm_client.py generate report \
  --notebook NOTEBOOK_ID \
  --format briefing_doc

# 6. Study Guide (convenience shortcut for report format=study_guide)
python3 scripts/notebooklm_client.py generate report \
  --notebook NOTEBOOK_ID \
  --format study_guide

# 7. Quiz
python3 scripts/notebooklm_client.py generate quiz \
  --notebook NOTEBOOK_ID \
  --quantity standard \
  --difficulty medium

# 8. Flashcards
python3 scripts/notebooklm_client.py generate flashcards \
  --notebook NOTEBOOK_ID

# 9. Mind Map
python3 scripts/notebooklm_client.py generate mind-map \
  --notebook NOTEBOOK_ID

# 10. Infographic — ⚠️ download unreliable, use slides instead
# python3 scripts/notebooklm_client.py generate infographic \
#   --notebook NOTEBOOK_ID \
#   --orientation landscape \
#   --detail standard

# 11. Data Table
python3 scripts/notebooklm_client.py generate data-table \
  --notebook NOTEBOOK_ID \
  --instructions "Compare frameworks by features, performance, and community size"

Artifact Generation Options

Audio formats:

| Format | Duration | Style | Best For | |---|---|---|---| | deep_dive | 15-30 min | Thorough exploration | Complex topics | | brief | 3-5 min | Quick overview | News updates | | critique | 10-20 min | Critical analysis | Reviews, evaluations | | debate | 10-20 min | Two opposing views | Controversial topics |

Audio lengths: short (~5 min), default (~10-15 min), long (~20-30 min)

Video formats: explainer, brief, cinematic (AI Ultra only)

Video styles: auto_select, classic, whiteboard, conversational, dynamic

Report formats: briefing_doc, study_guide, blog_post, custom (with --prompt)

Quiz options: quantity (fewer, standard, more), difficulty (easy, medium, hard)

Infographic options: orientation (landscape, portrait, square), detail (concise, standard, detailed)

Slide deck formats: detailed_deck, presenter_slides

Download Artifacts

Built-in CLI:

notebooklm download audio NOTEBOOK_ID output.m4a
notebooklm download video NOTEBOOK_ID output.mp4

Our wrapper CLI:

# Download audio (M4A)
python3 scripts/notebooklm_client.py download audio \
  --notebook NOTEBOOK_ID \
  --output podcast.m4a

# Download video (MP4)
python3 scripts/notebooklm_client.py download video \
  --notebook NOTEBOOK_ID \
  --output video.mp4

# Download slide deck (PDF)
python3 scripts/notebooklm_client.py download slide-deck \
  --notebook NOTEBOOK_ID \
  --output slides.pdf

# Get report content (Markdown)
python3 scripts/notebooklm_client.py download report \
  --notebook NOTEBOOK_ID \
  --output report.md

# Export quiz as JSON
python3 scripts/notebooklm_client.py download quiz \
  --notebook NOTEBOOK_ID \
  --format json \
  --output quiz.json

# Export flashcards
python3 scripts/notebooklm_client.py download flashcards \
  --notebook NOTEBOOK_ID \
  --output flashcards.json

# Export mind map as JSON
python3 scripts/notebooklm_client.py download mind-map \
  --notebook NOTEBOOK_ID \
  --output mindmap.json

# Export data table as CSV
python3 scripts/notebooklm_client.py download data-table \
  --notebook NOTEBOOK_ID \
  --output comparison.csv

Notebook Management

# List all notebooks
python3 scripts/notebooklm_client.py list
notebooklm notebook list

# Get notebook summary and suggested topics
python3 scripts/notebooklm_client.py describe --notebook NOTEBOOK_ID

# List sources in a notebook
python3 scripts/notebooklm_client.py sources --notebook NOTEBOOK_ID

# Get source guide (AI summary + keywords for a specific source)
python3 scripts/notebooklm_client.py source-guide --notebook NOTEBOOK_ID --source SOURCE_ID

# Get full indexed text of a source
python3 scripts/notebooklm_client.py fulltext --notebook NOTEBOOK_ID --source SOURCE_ID

# Rename notebook
python3 scripts/notebooklm_client.py rename --notebook NOTEBOOK_ID --title "New Title"

# Delete notebook
python3 scripts/notebooklm_client.py delete --notebook NOTEBOOK_ID

# Share notebook (public link)
python3 scripts/notebooklm_client.py share --notebook NOTEBOOK_ID --public
notebooklm share NOTEBOOK_ID --public
notebooklm share NOTEBOOK_ID --add user@example.com

Phase 3: CREATE -- Content Generation

Claude uses research output from Phase 2 to write original content. NotebookLM artifacts can also be used directly (reports, podcasts, slide decks).

Research-to-Article Pipeline

# Full pipeline: create notebook -> ask questions -> write article
python3 scripts/pipeline.py research-to-article \
  --sources "https://url1.com" "https://url2.com" \
  --title "AI Agent Frameworks in 2026" \
  --output article.md

# From existing notebook
python3 scripts/pipeline.py research-to-article \
  --notebook NOTEBOOK_ID \
  --topic "AI Agent Frameworks" \
  --output article.md

Research-to-Social Pipeline

# Research -> social posts for Threads/IG/FB
python3 scripts/pipeline.py research-to-social \
  --sources "https://url1.com" "https://url2.com" \
  --platform threads \
  --output posts.json

Trend-to-Content Pipeline (requires trend-pulse MCP)

# Discover trending topic -> research it -> create content
python3 scripts/pipeline.py trend-to-content \
  --geo TW \
  --count 3 \
  --platform threads \
  --output content.json

The trend-to-content pipeline:

1. Calls trend-pulse get_trending(geo="TW", count=20) to discover hot topics
2. Claude picks the best topic for the target niche
3. Creates a NotebookLM notebook with relevant URLs (from trend sources)
4. Asks research questions to build understanding
5. Claude writes platform-specific content using cited research

Batch Digest Pipeline

# RSS feed -> notebook -> digest summary
python3 scripts/pipeline.py batch-digest \
  --rss "https://example.com/feed.xml" \
  --title "Weekly AI Digest" \
  --max-entries 15

Integration with trend-pulse MCP

When trend-pulse MCP is available, use its tools directly:

get_trending(sources="hackernews,reddit", geo="TW", count=20)
-> Pick relevant topics
-> Feed URLs into NotebookLM notebook
-> Research and create content

Research-and-Write Workflow (Manual)

User: "Research AI agent frameworks and write a blog post"

1. Create notebook with relevant URLs (from search or user-provided)
2. Run deep web research to discover additional sources
3. Import top discovered sources into the notebook
4. Ask 3-5 research questions covering key angles
5. Generate a briefing doc report for structured overview
6. Generate a data table for feature comparison
7. Claude writes article using:
   - Cited answers from step 4
   - Report summary from step 5
   - Data table from step 6
   - Original analysis and opinion
8. Output polished markdown article with source citations

Artifacts as Direct Content

Some NotebookLM artifacts are usable directly without Claude rewriting:

| Artifact | Direct Use | Claude Enhancement | |---|---|---| | Audio (podcast) | Distribute as-is | Generate show notes, write companion article | | Video | Distribute as-is | Write video description, social posts | | Report (briefing doc) | Publish as blog post | Edit tone, add opinion, localize | | Slide deck | Present as-is (PDF) | Add speaker notes, create handout | | Quiz | Use for training/education | Adapt for social engagement (polls) | | Flashcards | Use for study | Convert to Threads carousel | | Mind map | Visual overview | Narrate as article outline | | Infographic | Share on social media | Write accompanying caption | | Data table | Embed in articles | Narrate findings, add analysis | | Study guide | Distribute for learning | Condense into social-sized tips |

Phase 4: PUBLISH -- Distribution (Optional)

Integration with threads-viral-agent

If the threads-viral-agent skill is available, pipe content directly:

# Research -> social post -> publish to Threads
python3 scripts/pipeline.py research-to-social \
  --notebook NOTEBOOK_ID \
  --topic "Topic" \
  --publish \
  --account cw

Direct Output Formats

Without social integration, output as files:

| Format | Use Case | Output | |---|---|---| | Markdown article | Blog post, website | .md file | | Social post JSON | Manual posting | .json with platform-specific text | | Newsletter draft | Email campaign | .md with sections | | Report (briefing doc) | Internal use, blog | Markdown from NotebookLM | | Podcast audio | Distribution | .m4a from NotebookLM audio artifact | | Video | Social media, YouTube | .mp4 from NotebookLM video artifact | | Slide deck | Presentations | .pdf from NotebookLM slide deck | | Quiz / Flashcards | Education, training | .json structured data | | Infographic | Social media, reports | Image from NotebookLM | | Data table | Analysis, spreadsheets | .csv export |

Full Auto-Pilot Mode

When the user says anything like "research this topic", "create a notebook about X", "turn these articles into a post", "research pipeline", "generate a podcast from these sources", "make a quiz", execute the complete flow.

Single Run

1. Collect source URLs from user or trend-pulse
2. Create notebook: notebooklm_client.py create --title "Topic" --sources url1 url2
3. Optionally run deep web research to discover more sources
4. Wait for source processing
5. Ask research questions: notebooklm_client.py ask --query "Q1"
6. Generate requested artifacts (audio, video, report, quiz, slides, etc.)
7. Claude writes content using research answers (with citations)
8. Output article/posts/report + downloadable artifacts

Deep Research Flow

User: "Deep dive into AI coding assistants"

1. Create notebook with user-provided or searched URLs
2. Run deep web research: research --mode deep --query "AI coding assistants 2026"
3. Poll results, import top 5 discovered sources
4. Ask 3-5 probing questions
5. Generate podcast (deep_dive format, long length)
6. Generate briefing doc report
7. Generate data table (feature comparison)
8. Download all artifacts
9. Claude writes companion article using cited research
10. Output: article.md + podcast.m4a + report.md + comparison.csv

Artifact Generation Flow

User: "Generate a quiz and flashcards from my notebook"

1. Find notebook by name or ID
2. Generate quiz: generate quiz --quantity standard --difficulty medium
3. Generate flashcards: generate flashcards
4. Wait for both to complete (poll_status / wait_for_completion)
5. Download quiz: download quiz --output quiz.json
6. Download flashcards: download flashcards --output flashcards.json
7. Output both files

MCP Server

The mcp_server/ directory contains a FastMCP server that exposes NotebookLM operations as MCP tools. Works with Claude Code, Cursor, Gemini CLI, and any MCP-compatible client.

Configuration

After pip install .:

{
  "mcpServers": {
    "notebooklm": {
      "command": "notebooklm-mcp"
    }
  }
}

Or using script path:

{
  "mcpServers": {
    "notebooklm": {
      "command": "python3",
      "args": ["/path/to/notebooklm-skill/mcp_server/server.py"]
    }
  }
}

HTTP mode (for remote / multi-client access):

notebooklm-mcp --http --port 8765

{
  "mcpServers": {
    "notebooklm": {
      "url": "http://localhost:8765/mcp"
    }
  }
}

MCP Tools (13 tools)

Core notebook operations (7):

| Tool | Parameters | Description | |---|---|---| | nlm_create_notebook(title, sources[], text_sources?) | title, URL list, optional text list | Create notebook and add sources | | nlm_list() | -- | List all notebooks | | nlm_delete(notebook) | notebook ID or title | Delete a notebook (irreversible) | | nlm_add_source(notebook, url?, text?, file_path?) | notebook + source | Add a source to existing notebook | | nlm_ask(notebook, query) | notebook ID/title, question | Ask question, get cited answer | | nlm_summarize(notebook) | notebook ID or title | Get comprehensive summary | | nlm_list_sources(notebook) | notebook ID or title | List all sources in notebook |

Artifact operations (3):

| Tool | Parameters | Description | |---|---|---| | nlm_generate(notebook, type, lang?, instructions?) | notebook, artifact type | Generate any of 9 artifact types (infographic excluded) | | nlm_download(notebook, type, output_path) | notebook, artifact type, output | Download artifact to file | | nlm_list_artifacts(notebook, type?) | notebook ID, optional type filter | List artifacts in notebook |

Research operations (1):

| Tool | Parameters | Description | |---|---|---| | nlm_research(notebook, query, mode?) | notebook, search query, mode | Run web research (fast or deep) |

Pipeline operations (2):

| Tool | Parameters | Description | |---|---|---| | nlm_research_pipeline(sources[], questions[], output_format?) | URLs, questions, format | Full research-to-content pipeline | | nlm_trend_research(geo?, count?, platform?) | region, count, platform | Trending topics to researched content |

Built-in CLI Reference (notebooklm-py)

The notebooklm CLI is installed with pip install notebooklm and mirrors the Python API directly.

Authentication

notebooklm login                              # One-time browser auth
notebooklm login --check                      # Verify stored session

Notebooks

notebooklm notebook list                      # List all notebooks
notebooklm notebook create "Title"            # Create notebook
notebooklm notebook get NOTEBOOK_ID           # Get notebook details
notebooklm notebook delete NOTEBOOK_ID        # Delete notebook
notebooklm notebook rename NOTEBOOK_ID "New"  # Rename notebook

Sources

notebooklm source list NOTEBOOK_ID                         # List sources
notebooklm source add NOTEBOOK_ID --url "https://..."      # Add URL
notebooklm source add NOTEBOOK_ID --text "T" --content "." # Add text
notebooklm source add NOTEBOOK_ID --file /path/to/doc.pdf  # Add file
notebooklm source delete NOTEBOOK_ID SOURCE_ID             # Delete source
notebooklm source guide NOTEBOOK_ID SOURCE_ID              # AI summary + keywords
notebooklm source fulltext NOTEBOOK_ID SOURCE_ID           # Full indexed text

Chat

notebooklm chat NOTEBOOK_ID "Question?"                    # Ask question
notebooklm chat NOTEBOOK_ID "Follow up" --conversation ID  # Follow-up

Artifact Generation

notebooklm generate audio NOTEBOOK_ID                      # Podcast
notebooklm generate video NOTEBOOK_ID                      # Video
notebooklm generate report NOTEBOOK_ID --format briefing_doc
notebooklm generate quiz NOTEBOOK_ID
notebooklm generate flashcards NOTEBOOK_ID
# notebooklm generate infographic NOTEBOOK_ID  # ⚠️ download unreliable
notebooklm generate slide-deck NOTEBOOK_ID
notebooklm generate data-table NOTEBOOK_ID
notebooklm generate mind-map NOTEBOOK_ID

Download

notebooklm download audio NOTEBOOK_ID output.m4a           # Download podcast
notebooklm download video NOTEBOOK_ID output.mp4           # Download video
notebooklm download slide-deck NOTEBOOK_ID output.pdf      # Download slides

Research

notebooklm research start NOTEBOOK_ID "query"              # Start research
notebooklm research poll NOTEBOOK_ID                       # Poll results

Sharing

notebooklm share NOTEBOOK_ID --public                      # Enable public link
notebooklm share NOTEBOOK_ID --add user@example.com        # Share with user

Our Wrapper CLI Reference (scripts/)

notebooklm_client.py -- Core Operations

| Subcommand | Description | Key Flags | |---|---|---| | create | Create notebook with sources | --title, --sources, --text-sources | | ask | Ask question, get cited answer | --notebook, --query, --sources, --conversation | | summarize | Summarize notebook content | --notebook | | podcast | Generate audio overview | --notebook, --lang | | qa | Generate Q&A pairs | --notebook, --count | | list | List all notebooks | -- | | delete | Delete a notebook | --notebook | | add-source | Add source to notebook | --notebook, --url/--text/--file/--drive-id | | describe | Get AI summary + topics | --notebook | | sources | List sources in notebook | --notebook | | source-guide | Get AI summary of source | --notebook, --source | | fulltext | Get full source text | --notebook, --source | | rename | Rename notebook | --notebook, --title | | share | Share notebook | --notebook, --public | | generate | Generate any artifact type | --notebook, --type, --format, --language | | download | Download artifact | --notebook, --type, --output | | research | Start web/drive research | --notebook, --query, --source, --mode | | research-poll | Poll research results | --notebook, --import-top |

pipeline.py -- Higher-Level Workflows

| Workflow | Description | Key Flags | |---|---|---| | research-to-article | Sources -> research -> article | --sources, --title, --output | | research-to-social | Sources -> summarize -> social post | --sources, --platform, --output | | trend-to-content | Trends -> research -> content | --geo, --count, --platform | | batch-digest | RSS feed -> digest summary | --rss, --title, --max-entries |

Rate Limits

These are estimated safe limits. Actual limits are undocumented and may vary. If you receive rate limit errors, wait 60 seconds and retry.

| Operation | Limit | Notes | |---|---|---| | Notebook creation | ~10/hour | Suggested safe rate | | Source addition | ~20/hour | Per notebook | | Chat questions | ~30/hour | Across all notebooks | | Audio generation | ~5/hour | Resource-intensive, 3-10 min processing | | Video generation | ~3/hour | Very resource-intensive, 5-15 min processing | | Cinematic video | ~2/hour | Veo 3 rendering, AI Ultra only | | Report generation | ~10/hour | Moderate, 10-60 sec processing | | Quiz/Flashcards | ~10/hour | Moderate | | Slide deck | ~5/hour | Moderate-heavy | | Infographic | ~5/hour | Moderate-heavy | | Data table | ~10/hour | Moderate | | Mind map | ~10/hour | Lightweight | | Web research (fast) | ~10/hour | Google search backend | | Web research (deep) | ~5/hour | Extended processing |

Rate limit detection: The API returns is_rate_limited: true in GenerationStatus. The error code is "USER_DISPLAYABLE_ERROR". Wait 60 seconds and retry.

Error Handling

The API provides a structured error hierarchy:

NotebookLMError (base)
+-- AuthError              # Session expired -> run `notebooklm login`
+-- RPCError               # Google RPC failures
|   +-- RPCTimeoutError    # Increase timeout
+-- SourceError
|   +-- SourceAddError     # Bad URL or file format
|   +-- SourceTimeoutError # Source took too long to process
+-- ArtifactError
|   +-- ArtifactNotReadyError  # Poll again or wait
+-- RateLimitError         # Wait 60s and retry

Common fixes:

• AuthError: Run notebooklm login to refresh the session
• SourceTimeoutError: Increase wait_timeout or check source URL
• RateLimitError: Wait 60 seconds, then retry
• ArtifactNotReadyError: Use wait_for_completion() instead of immediate download

Quick Reference: All Components

| Component | Path | Purpose | |---|---|---| | scripts/notebooklm_client.py | scripts/ | Core CLI (also: notebooklm-skill after pip install) | | scripts/pipeline.py | scripts/ | Higher-level pipelines (also: notebooklm-pipeline after pip install) | | mcp_server/server.py | mcp_server/ | FastMCP server (also: notebooklm-mcp after pip install) | | mcp_server/tools.py | mcp_server/ | MCP tool implementations | | scripts/auth_helper.py | scripts/ | Authentication helper | | references/api_surface.md | references/ | Full notebooklm-py v0.3.4 API documentation (8 sub-APIs, all methods) | | references/output_formats.md | references/ | JSON output format specifications for all API responses | | references/pipeline_recipes.md | references/ | 7 common pipeline recipes with full command sequences | | docs/SETUP.md | docs/ | Installation and setup guide |

Quick Reference: 10 Artifact Types

| Type | Generate | Download | Output Format | Processing Time | |---|---|---|---|---| | Audio (podcast) | generate audio | download audio | M4A | 3-10 min | | Video | generate video | download video | MP4 | 5-15 min | | Cinematic Video | generate cinematic-video | download video | MP4 | 10-20 min | | Slide Deck | generate slide-deck | download slide-deck | PDF | 30-120 sec | | Report | generate report | download report | Markdown | 10-60 sec | | Study Guide | generate report --format study_guide | download report | Markdown | 10-60 sec | | Quiz | generate quiz | download quiz | JSON (structured) | 10-30 sec | | Flashcards | generate flashcards | download flashcards | JSON (structured) | 10-30 sec | | Mind Map | generate mind-map | download mind-map | JSON (tree) | 5-15 sec | | ~~Infographic~~ | ~~generate infographic~~ | ~~download infographic~~ | ~~Image~~ | ⚠️ download unreliable — use slides | | Data Table | generate data-table | download data-table | CSV/JSON | 10-30 sec |

Trigger Patterns

English

• "Research X using NotebookLM"
• "Create a notebook about X"
• "Turn these articles into a blog post"
• "Generate a podcast from these sources"
• "Generate a video overview of X"
• "Make a slide deck from this research"
• "Create a quiz from this material"
• "Generate flashcards for studying X"
• "Create an infographic about X" (⚠️ use slides instead — infographic download unreliable)
• "Build a mind map of X"
• "Generate a data table comparing X and Y"
• "Write a report on X"
• "Deep research on X"
• "Find sources about X"
• "What does the research say about X?"
• "Research and write about X"
• "Summarize these sources"
• "Research pipeline for X"
• "Compare these sources"
• "Turn this into a study guide"
• "Research trending topics and write content"
• "Create a weekly digest from these feeds"

ZH-TW

• "用 NotebookLM 研究 X"
• "建立一個關於 X 的筆記本"
• "把這些文章變成部落格文章"
• "從這些來源生成 Podcast"
• "幫我做一個影片摘要"
• "做一份簡報 / 投影片"
• "從這些資料出題 / 出考卷"
• "幫我做閃卡 / 字卡"
• "做一張資訊圖表"
• "畫一個心智圖"
• "做一個比較表格"
• "寫一份報告"
• "深入研究 X"
• "幫我找 X 的資料"
• "研究 X 並寫一篇文章"
• "幫我整理這些資料"
• "研究流水線"
• "比較這些來源"
• "做一份讀書指南"
• "研究熱門趨勢並寫內容"
• "做每週摘要"

Quick Start

# Option A: uvx (recommended — zero install)
uvx notebooklm-skill --help
uvx --from notebooklm-skill notebooklm-mcp   # Start MCP server

# Option B: pip install from PyPI
pip install notebooklm-skill

# Option C: Install from source
git clone https://github.com/claude-world/notebooklm-skill.git
cd notebooklm-skill && pip install .

# Option D: One-line install (pip + Playwright + Claude Code Skill)
git clone https://github.com/claude-world/notebooklm-skill.git
cd notebooklm-skill && ./install.sh

# Authenticate with Google (one-time, opens browser)
uvx notebooklm login              # if using uvx
# or: python3 -m notebooklm login  # if using pip install

# Use commands (uvx or direct — both work the same)
notebooklm-skill create --title "My Research" --sources https://example.com/article
notebooklm-skill ask --notebook "My Research" --query "What are the key findings?"
notebooklm-skill podcast --notebook "My Research" --lang en --output podcast.m4a
notebooklm-pipeline research-to-article --sources https://example.com --title "Topic"
notebooklm-mcp                   # Start MCP server (stdio mode)

Or use scripts directly: python scripts/notebooklm_client.py create ...

See docs/SETUP.md for the full setup guide.

Authentication

notebooklm-py uses browser-based Google login. No API keys, no OAuth Client ID, no Google Cloud project needed.

# One-time login (opens Chromium, sign in with Google)
uvx notebooklm login              # if using uvx
python3 -m notebooklm login       # if using pip install

| Step | Command | What happens | |------|---------|-------------| | Login | uvx notebooklm login | Opens Chromium, user logs into Google | | Session storage | Automatic | Saved to ~/.notebooklm/storage_state.json | | Subsequent use | All CLI / MCP commands | Reads saved session, pure HTTP calls | | Verify | uvx notebooklm-skill list | Lists notebooks to confirm auth works | | Clear | rm -rf ~/.notebooklm | Removes stored session |

Session typically lasts weeks. Re-run login if you get authentication errors.

Two Ways to Use

| | Claude Code Skill | MCP Server | |---|---|---| | Best for | Claude Code users who want NotebookLM in their workflow | Any MCP-compatible client (Cursor, Gemini CLI, etc.) | | Setup | Copy skill to .claude/skills/ | Add server to MCP config | | Invocation | Claude auto-detects when relevant | Tools appear in client tool list | | Config | SKILL.md + .env | .mcp.json + .env | | Requirements | Python 3.10+, notebooklm-py | Python 3.10+, notebooklm-py |

Features

| Feature | Description | Status | |---|---|---| | Notebook CRUD | Create, list, delete notebooks | Available | | Source ingestion | Add URLs, PDFs, YouTube links, plain text | Available | | Research queries | Ask questions against notebook sources with citations | Available | | Structured extraction | Get key facts, arguments, timelines | Available | | Content generation | Use research output as context for Claude | Available | | Batch operations | Process multiple sources or queries at once | Available | | trend-pulse integration | Auto-discover trending topics to research | Available | | threads-viral-agent integration | Publish research-backed social posts | Available |

Artifact Generation (9 downloadable types)

| Artifact | Format | Description | |---|---|---| | Audio | M4A | AI-generated podcast discussion | | Video | MP4 | Video summary with visuals | | Slides | PDF / PPTX | Presentation deck | | Report | Markdown | Comprehensive written report | | Quiz | JSON / Markdown / HTML | Multiple-choice assessment questions | | Flashcards | JSON / Markdown / HTML | Study flashcard deck | | Mind map | JSON | Visual concept map | | Infographic | PNG | Visual data summary | | Data table | CSV | Structured data extraction | | Study guide | Markdown | Structured learning material |

Most artifacts support language selection (e.g., --lang zh-TW). Exceptions: quiz, flashcards, mind-map.

Note: NotebookLM returns audio in MPEG-4 (M4A) format, not MP3.

Architecture

+---------------------------------------------------------------+
|                      notebooklm-skill                          |
|                                                                |
|  +---------+  +--------------+  +----------+  +------------+  |
|  | Phase 1 |  |   Phase 2    |  |  Phase 3 |  |  Phase 4   |  |
|  | Collect  |->|  Research    |->| Generate  |->|  Publish   |  |
|  +---------+  +--------------+  +----------+  +------------+  |
|      |              |                |               |         |
|  +--------+  +-------------+  +-----------+  +-----------+    |
|  | URLs   |  | NotebookLM  |  |  Claude    |  | Threads   |    |
|  | PDFs   |  | (via        |  |  Content   |  | Blog      |    |
|  | RSS    |  |  notebooklm |  |  Engine    |  | Email     |    |
|  | Trends |  |  -py 0.3.4) |  |            |  | CMS       |    |
|  +--------+  | - notebooks |  +-----------+  +-----------+    |
|              | - sources   |        |                          |
|              | - chat/ask  |  +-----------+                    |
|              | - artifacts |  | Artifacts |                    |
|              +-------------+  | audio     |                    |
|                               | video     |                    |
|                               | slides    |                    |
|                               | report    |                    |
|                               | quiz      |                    |
|                               | flashcards|                    |
|                               | mind-map  |                    |
|                               | infographic| ⚠️ no download    |
|                               | data-table|                    |
|                               | study-guide|                   |
|                               +-----------+                    |
|                                                                |
|  +-----------------------------------------------------------+ |
|  |  Interfaces                                                | |
|  |  +-- scripts/          CLI tools (notebooklm-py direct)   | |
|  |  +-- mcp_server/       MCP protocol server                 | |
|  |  +-- SKILL.md          Claude Code skill definition        | |
|  +-----------------------------------------------------------+ |
+---------------------------------------------------------------+
         ^                                          ^
         |                                          |
   +-----------+                             +-----------+
   |trend-pulse|                             |threads-   |
   |(optional) |                             |viral-agent|
   +-----------+                             |(optional) |
                                             +-----------+

Usage Examples

1. Research to Article

python scripts/pipeline.py research-to-article \
  --sources "https://arxiv.org/abs/2401.00001" \
            "https://blog.example.com/ai-agents" \
  --title "AI Agent Survey"

2. Research to Social Posts

python scripts/pipeline.py research-to-social