notebooklm-research
Automate source-grounded research with Google NotebookLM. Create notebooks from URLs, text, or local files; ask cited questions; run fast or deep web research; create articles and social drafts; and generate or download audio, video, cinematic video, slides, reports, study guides, quizzes, flashcards, mind maps, infographics, and data tables. Use when a user asks for NotebookLM, cited source analysis, research-to-content workflows, podcasts, slides, study material, artifact generation, RSS digests, or trend research.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/claude-world--notebooklm-skill)HTML
<a href="/listings/claude-world--notebooklm-skill"><img src="/api/listings/claude-world--notebooklm-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Isolated source install
The installer creates a dedicated virtual environment, installs Chromium, links five commands into `~/.local/bin`, and installs the Claude Code Skill using the standard directory layout.
git clone https://github.com/claude-world/notebooklm-skill.git cd notebooklm-skill ./install.sh notebooklm-auth setup notebooklm-skill list
Ensure `~/.local/bin` is on `PATH`.
PyPI or uvx
# Persistent virtual environment python3 -m venv .venv source .venv/bin/activate python -m pip install notebooklm-skill python -m playwright install chromium notebooklm-auth setup # Or run without a persistent install uvx --from notebooklm-skill notebooklm-auth setup uvx --from notebooklm-skill notebooklm-skill list
Direct upstream login is also available:
uvx --from notebooklm-py notebooklm login
Sessions are profile-aware. Select one with `--profile NAME` before a CLI subcommand, or set `NOTEBOOKLM_PROFILE`.
To use the locally installed Google Chrome instead of bundled Chromium:
notebooklm-auth setup --browser chrome --fresh
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 231 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: notebooklm-research
- description: >
- Automate source-grounded research with Google NotebookLM. Create notebooks from
- URLs, text, or local files; ask cited questions; run fast or deep web research;
- create articles and social drafts; and generate or download audio, video,
- cinematic video, slides, reports, study guides, quizzes, flashcards, mind maps,
- infographics, and data tables. Use when a user asks for NotebookLM, cited source
- analysis, research-to-content workflows, podcasts, slides, study material,
- artifact generation, RSS digests, or trend research.
- license: MIT
- compatibility: >
- Requires Python 3.10+, the notebooklm-skill package (pip install or uvx), network
- access, and a Google account signed in to NotebookLM with notebooklm-auth setup.
- ---
- # NotebookLM Research
- Use the installed commands or the 13 MCP tools to turn user-provided sources into
- grounded answers and NotebookLM artifacts. Commands emit JSON on stdout and progress
- or diagnostics on stderr, so preserve stdout when another tool will consume it.
- This integration uses NotebookLM's browser session and unofficial web API through
- `notebooklm-py`. Do not promise that Google-side availability, quotas, or generation
- time are stable.
- ## Authentication
- Prefer the profile-aware helper:
- ```bash
- notebooklm-auth setup
- notebooklm-auth verify
- ```
- Use `notebooklm-auth setup --browser chrome --fresh` when the user explicitly
- wants the locally installed Google Chrome instead of bundled Chromium.
- For a zero-install login:
- ```bash
- uvx --from notebooklm-py notebooklm login
- ```
- Profiles are supported through `--profile NAME` before the subcommand or through
- `NOTEBOOKLM_PROFILE`. Current sessions are normally stored below
- `~/.notebooklm/profiles/<profile>/storage_state.json`; never read, print, copy, or
- commit that file. If authentication expires, run setup again.
- ## Core CLI
- Create a notebook from mixed sources:
- ```bash
- notebooklm-skill create \
- --title "AI safety evidence" \
- --sources https://example.com/article https://youtu.be/example \
- --files ./paper.pdf \
- --text-sources "A user-supplied observation" \
- --strict
- ```
- Inspect and ask:
- ```bash
- notebooklm-skill list
- notebooklm-skill list-sources --notebook "AI safety evidence"
- notebooklm-skill summarize --notebook "AI safety evidence"
- notebooklm-skill ask --notebook "AI safety evidence" --query "What findings conflict?"
- ```
- Add exactly one source:
- ```bash
- notebooklm-skill add-source --notebook "AI safety evidence" --url https://example.com/new
- notebooklm-skill add-source --notebook "AI safety evidence" --file ./appendix.docx
- notebooklm-skill add-source --notebook "AI safety evidence" \
- --text "Raw notes" --text-title "Interview notes"
- ```
- Run NotebookLM web research and import results:
- ```bash
- notebooklm-skill research \
- --notebook "AI safety evidence" \
- --query "Recent empirical evaluations" \
- --mode deep --max-sources 10
- ```
- Use `--no-wait` for a task ID without waiting. Use `--no-import-results` when the
- research results should not become notebook sources.
- Notebook titles may be used only when they resolve uniquely. Prefer IDs in automation.
- ## Artifact generation
- Supported canonical types:
- `audio`, `video`, `cinematic`, `slides`, `report`, `study-guide`, `quiz`,
- `flashcards`, `mind-map`, `infographic`, `data-table`.
- Generate and optionally download in one operation:
- ```bash
- notebooklm-skill generate \
- --notebook "AI safety evidence" \
- --type slides --lang zh-TW \
- --slide-format presenter-slides \
- --output ./output/deck.pptx --output-format pptx
- ```
- Long media jobs can be detached and downloaded later by exact ID:
- ```bash
- notebooklm-skill generate --notebook NOTEBOOK_ID --type audio --no-wait
- notebooklm-skill list-artifacts --notebook NOTEBOOK_ID --type audio
- notebooklm-skill download --notebook NOTEBOOK_ID --type audio \
- --artifact-id ARTIFACT_ID --output ./output/podcast.m4a
- ```
- Convenience commands:
- ```bash
- notebooklm-skill podcast --notebook NOTEBOOK_ID --output podcast.m4a
- notebooklm-skill qa --notebook NOTEBOOK_ID --difficulty hard --output quiz.json
- ```
- Generation supports per-type options, including `--video-format short` for a
- vertical short video (fixed style, so no `--video-style` or `--style-prompt`) and
- `--quantity more` for larger quizzes and flashcard sets. Inspect the live contract
- before composing an unfamiliar call:
- ```bash
- notebooklm-skill generate --help
- ```
- Existing output files and symlinks are rejected. Use `--force` only when the user
- explicitly wants an overwrite. Quiz and flashcard downloads support JSON, Markdown,
- or HTML; slide downloads support PDF or PPTX.
- ## High-level pipelines
- ```bash
- notebooklm-pipeline research-to-article \
- --sources https://example.com/a https://example.com/b \
- --title "Evidence review" --language zh-TW --audience "engineers"
- notebooklm-pipeline research-to-social \
- --sources https://example.com/a --platform threads --variants 3
- notebooklm-pipeline batch-digest \
- --rss https://example.com/feed.xml --max-entries 20 --qa-count 5
- notebooklm-pipeline generate-all \
- --files ./paper.pdf --types audio slides report mind-map \
- --output-dir ./output --artifact-concurrency 2
- ```
- `trend-to-content` requires a separately installed `trend-pulse` command. Override
- its executable safely with `TREND_PULSE_CMD`; the integration does not invoke a shell.
- Pipelines create drafts and local artifacts. They do not publish to social networks,
- CMS products, or other remote destinations.
- ## MCP server
- Start stdio mode for an MCP client:
- ```bash
- notebooklm-mcp
- ```
- Example configuration:
- ```json
- {
- "mcpServers": {
- "notebooklm": {
- "command": "uvx",
- "args": ["--from", "notebooklm-skill", "notebooklm-mcp"]
- }
- }
- }
- ```
- Available tools:
- - `nlm_create_notebook`, `nlm_list`, `nlm_delete`
- - `nlm_add_source`, `nlm_list_sources`
- - `nlm_ask`, `nlm_summarize`
- - `nlm_generate`, `nlm_download`, `nlm_list_artifacts`
- - `nlm_research`, `nlm_research_pipeline`, `nlm_trend_research`
- Notebook deletion requires `confirm=true`. HTTP mode binds only to loopback:
- ```bash
- notebooklm-mcp --http --host 127.0.0.1 --port 8765
- ```
- Do not expose HTTP mode directly to a network. If remote access is unavoidable, put
- it behind an authenticated TLS proxy and apply host-level access controls.
- ## Operating rules
- 1. Verify authentication before a long workflow.
- 2. Confirm sources were ingested; treat `partial` or failed source entries honestly.
- 3. Ask focused questions and retain returned citation metadata.
- 4. Use exact notebook and artifact IDs in repeated automation.
- 5. Use bounded source/artifact concurrency; generation is quota-sensitive.
- 6. Do not delete notebooks or overwrite output without explicit user intent.
- 7. Do not claim a draft was published; no publishing integration exists here.
- 8. Return the JSON result or a faithful summary, including partial failures.
- ## Exit codes and recovery
- - `0`: operation completed successfully.
- - `2`: invalid or ambiguous arguments.
- - `4`: authentication required.
- - `1`: upstream, network, generation, or other operational failure.
- - `130`: interrupted by the user.
- Common recovery:
- ```bash
- notebooklm-auth verify
- notebooklm-auth setup # missing or expired session
- notebooklm-skill list-artifacts --notebook NOTEBOOK_ID # inspect a timed-out job
- ```
- Use `notebooklm-skill --help`, `notebooklm-pipeline --help`, and the relevant
- subcommand's `--help` as the authoritative local command contract.
README.md · README · 221 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # notebooklm-skill
- > Source-grounded NotebookLM automation for terminals and AI agents.
- [](https://github.com/claude-world/notebooklm-skill/actions/workflows/ci.yml)
- [](https://pypi.org/project/notebooklm-skill/)
- [](https://pypi.org/project/notebooklm-skill/)
- [](LICENSE)
- [繁體中文](README.zh-TW.md)
- `notebooklm-skill` gives humans and MCP clients one consistent interface for Google
- NotebookLM. It creates notebooks from URLs, raw text, and local files; asks grounded
- questions with citation metadata; completes fast or deep web research; and generates
- or downloads NotebookLM artifacts.
- The project is built on `notebooklm-py` 0.8.x and FastMCP 4 (MCP Python SDK 2.x),
- and includes:
- - a JSON-first core CLI;
- - five end-to-end research pipelines;
- - a 13-tool FastMCP server;
- - profile-aware authentication and Skill installers;
- - one shared compatibility layer, so CLI, pipelines, and MCP use the same behavior.
- > This is an unofficial integration with NotebookLM's web API. Google can change the
- > service, availability, quotas, or artifact behavior without notice.
- ## Requirements
- - Python 3.10 or newer (CI covers 3.10 through 3.15)
- - a Google account with access to NotebookLM
- - Chromium for the one-time browser login (installed by `./install.sh`), or a local
- Google Chrome or Microsoft Edge
- - optional: the `trend-pulse` command for trend workflows, and `ffmpeg` plus Poppler
- for `scripts/make_video.sh`
- ## Quick start
- ### Isolated source install
- The installer creates a dedicated virtual environment, installs Chromium, links five
- commands into `~/.local/bin`, and installs the Claude Code Skill using the standard
- directory layout.
- ```bash
- git clone https://github.com/claude-world/notebooklm-skill.git
- cd notebooklm-skill
- ./install.sh
- notebooklm-auth setup
- notebooklm-skill list
- ```
- Ensure `~/.local/bin` is on `PATH`.
- ### PyPI or uvx
- ```bash
- # Persistent virtual environment
- python3 -m venv .venv
- source .venv/bin/activate
- python -m pip install notebooklm-skill
- python -m playwright install chromium
- notebooklm-auth setup
- # Or run without a persistent install
- uvx --from notebooklm-skill notebooklm-auth setup
- uvx --from notebooklm-skill notebooklm-skill list
- ```
- Direct upstream login is also available:
- ```bash
- uvx --from notebooklm-py notebooklm login
- ```
- Sessions are profile-aware. Select one with `--profile NAME` before a CLI
- subcommand, or set `NOTEBOOKLM_PROFILE`.
- To use the locally installed Google Chrome instead of bundled Chromium:
- ```bash
- notebooklm-auth setup --browser chrome --fresh
- ```
- ## Core CLI
- All successful commands print structured JSON to stdout. Diagnostics go to stderr;
- authentication errors return exit code 4 and argument errors return exit code 2.
- ```bash
- # Mixed-source ingestion with truthful per-source outcomes
- notebooklm-skill create \
- --title "Research" \
- --sources https://example.com/article \
- --files ./paper.pdf \
- --text-sources "Interview notes" \
- --strict
- notebooklm-skill ask \
- --notebook "Research" \
- --query "Which conclusions have the strongest evidence?"
- notebooklm-skill research \
- --notebook "Research" \
- --query "Recent independent evaluations" \
- --mode deep --max-sources 10
- notebooklm-skill generate \
- --notebook "Research" \
- --type slides --lang zh-TW \
- --output ./output/deck.pptx --output-format pptx
- notebooklm-skill list-artifacts --notebook "Research" --type slides
- ```
- Commands resolve an exact ID, unique title, or unique title substring. Use IDs for
- repeatable automation. Deletes require `--yes`; downloads refuse existing files or
- symlinks unless an explicit safe overwrite is requested with `--force`.
- ### Artifact types
- | Type | Default download | Notes |
- |---|---:|---|
- | `audio` | M4A | deep-dive, brief, critique, or debate |
- | `video` | MP4 | explainer, brief, or vertical short; multiple visual styles |
- | `cinematic` | MP4 | cinematic video workflow |
- | `slides` | PDF | PDF or PPTX |
- | `report` | Markdown | briefing, study guide, blog, or custom |
- | `study-guide` | Markdown | report shortcut |
- | `quiz` | JSON | JSON, Markdown, or HTML; fewer, standard, or more questions |
- | `flashcards` | JSON | JSON, Markdown, or HTML; fewer, standard, or more cards |
- | `mind-map` | JSON | immediate generation result |
- | `infographic` | PNG | orientation, detail, and style options |
- | `data-table` | CSV | structured extraction |
- Use `notebooklm-skill generate --help` for the live option matrix. Long-running
- generations support `--no-wait`, and later downloads can select `--artifact-id`.
- ## Pipelines
- ```bash
- notebooklm-pipeline research-to-article \
- --sources https://example.com/a https://example.com/b \
- --title "Evidence review" --audience "engineers"
- notebooklm-pipeline research-to-social \
- --files ./brief.pdf --platform linkedin --variants 3
- notebooklm-pipeline batch-digest \
- --rss https://example.com/feed.xml --max-entries 20 --qa-count 5
- notebooklm-pipeline generate-all \
- --files ./paper.pdf --types audio slides report mind-map \
- --output-dir ./output --artifact-concurrency 2
- ```
- `trend-to-content` requires the optional `trend-pulse` command. Pipelines return
- drafts and local artifacts; they do not publish to social platforms or remote CMSs.
- ## MCP server
- The default stdio transport is suitable for Claude Code, Cursor, and other MCP
- clients:
- ```json
- {
- "mcpServers": {
- "notebooklm": {
- "command": "uvx",
- "args": ["--from", "notebooklm-skill", "notebooklm-mcp"]
- }
- }
- }
- ```
- The 13 tools cover notebook CRUD, mixed sources, grounded chat, summaries, artifact
- generation/list/download, full research lifecycles, research pipelines, and trend
- research. Notebook deletion requires `confirm=true`.
- Optional HTTP mode is deliberately loopback-only:
- ```bash
- notebooklm-mcp --http --host 127.0.0.1 --port 8765
- ```
- Do not expose it directly to a network. See [SECURITY.md](SECURITY.md).
- ## Additional commands
- | Command | Purpose |
- |---|---|
- | `notebooklm-auth` | Setup, verify, or clear a selected auth profile |
- | `notebooklm-install-skill` | Install `SKILL.md` for a user or project, with safe backups |
- ```bash
- notebooklm-install-skill --scope project
- notebooklm-auth --profile work verify
- ```
- ## Development
- ```bash
- python3 -m venv .venv
- source .venv/bin/activate
- python -m pip install -e '.[dev]'
- ruff check .
- ruff format --check .
- mypy scripts mcp_server
- pytest --cov --cov-report=term-missing
- python -m build
- twine check dist/*
- ```
- More detail: [setup guide](docs/SETUP.md), [Skill instructions](SKILL.md),
- [API compatibility notes](references/api_surface.md), and [changelog](CHANGELOG.md).
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.