Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/claude-world--notebooklm-skill/badge.svg)](/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

i

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.

  1. ---
  2. name: notebooklm-research
  3. description: >
  4. Automate source-grounded research with Google NotebookLM. Create notebooks from
  5. URLs, text, or local files; ask cited questions; run fast or deep web research;
  6. create articles and social drafts; and generate or download audio, video,
  7. cinematic video, slides, reports, study guides, quizzes, flashcards, mind maps,
  8. infographics, and data tables. Use when a user asks for NotebookLM, cited source
  9. analysis, research-to-content workflows, podcasts, slides, study material,
  10. artifact generation, RSS digests, or trend research.
  11. license: MIT
  12. compatibility: >
  13. Requires Python 3.10+, the notebooklm-skill package (pip install or uvx), network
  14. access, and a Google account signed in to NotebookLM with notebooklm-auth setup.
  15. ---
  16. # NotebookLM Research
  17. Use the installed commands or the 13 MCP tools to turn user-provided sources into
  18. grounded answers and NotebookLM artifacts. Commands emit JSON on stdout and progress
  19. or diagnostics on stderr, so preserve stdout when another tool will consume it.
  20. This integration uses NotebookLM's browser session and unofficial web API through
  21. `notebooklm-py`. Do not promise that Google-side availability, quotas, or generation
  22. time are stable.
  23. ## Authentication
  24. Prefer the profile-aware helper:
  25. ```bash
  26. notebooklm-auth setup
  27. notebooklm-auth verify
  28. ```
  29. Use `notebooklm-auth setup --browser chrome --fresh` when the user explicitly
  30. wants the locally installed Google Chrome instead of bundled Chromium.
  31. For a zero-install login:
  32. ```bash
  33. uvx --from notebooklm-py notebooklm login
  34. ```
  35. Profiles are supported through `--profile NAME` before the subcommand or through
  36. `NOTEBOOKLM_PROFILE`. Current sessions are normally stored below
  37. `~/.notebooklm/profiles/<profile>/storage_state.json`; never read, print, copy, or
  38. commit that file. If authentication expires, run setup again.
  39. ## Core CLI
  40. Create a notebook from mixed sources:
  41. ```bash
  42. notebooklm-skill create \
  43. --title "AI safety evidence" \
  44. --sources https://example.com/article https://youtu.be/example \
  45. --files ./paper.pdf \
  46. --text-sources "A user-supplied observation" \
  47. --strict
  48. ```
  49. Inspect and ask:
  50. ```bash
  51. notebooklm-skill list
  52. notebooklm-skill list-sources --notebook "AI safety evidence"
  53. notebooklm-skill summarize --notebook "AI safety evidence"
  54. notebooklm-skill ask --notebook "AI safety evidence" --query "What findings conflict?"
  55. ```
  56. Add exactly one source:
  57. ```bash
  58. notebooklm-skill add-source --notebook "AI safety evidence" --url https://example.com/new
  59. notebooklm-skill add-source --notebook "AI safety evidence" --file ./appendix.docx
  60. notebooklm-skill add-source --notebook "AI safety evidence" \
  61. --text "Raw notes" --text-title "Interview notes"
  62. ```
  63. Run NotebookLM web research and import results:
  64. ```bash
  65. notebooklm-skill research \
  66. --notebook "AI safety evidence" \
  67. --query "Recent empirical evaluations" \
  68. --mode deep --max-sources 10
  69. ```
  70. Use `--no-wait` for a task ID without waiting. Use `--no-import-results` when the
  71. research results should not become notebook sources.
  72. Notebook titles may be used only when they resolve uniquely. Prefer IDs in automation.
  73. ## Artifact generation
  74. Supported canonical types:
  75. `audio`, `video`, `cinematic`, `slides`, `report`, `study-guide`, `quiz`,
  76. `flashcards`, `mind-map`, `infographic`, `data-table`.
  77. Generate and optionally download in one operation:
  78. ```bash
  79. notebooklm-skill generate \
  80. --notebook "AI safety evidence" \
  81. --type slides --lang zh-TW \
  82. --slide-format presenter-slides \
  83. --output ./output/deck.pptx --output-format pptx
  84. ```
  85. Long media jobs can be detached and downloaded later by exact ID:
  86. ```bash
  87. notebooklm-skill generate --notebook NOTEBOOK_ID --type audio --no-wait
  88. notebooklm-skill list-artifacts --notebook NOTEBOOK_ID --type audio
  89. notebooklm-skill download --notebook NOTEBOOK_ID --type audio \
  90. --artifact-id ARTIFACT_ID --output ./output/podcast.m4a
  91. ```
  92. Convenience commands:
  93. ```bash
  94. notebooklm-skill podcast --notebook NOTEBOOK_ID --output podcast.m4a
  95. notebooklm-skill qa --notebook NOTEBOOK_ID --difficulty hard --output quiz.json
  96. ```
  97. Generation supports per-type options, including `--video-format short` for a
  98. vertical short video (fixed style, so no `--video-style` or `--style-prompt`) and
  99. `--quantity more` for larger quizzes and flashcard sets. Inspect the live contract
  100. before composing an unfamiliar call:
  101. ```bash
  102. notebooklm-skill generate --help
  103. ```
  104. Existing output files and symlinks are rejected. Use `--force` only when the user
  105. explicitly wants an overwrite. Quiz and flashcard downloads support JSON, Markdown,
  106. or HTML; slide downloads support PDF or PPTX.
  107. ## High-level pipelines
  108. ```bash
  109. notebooklm-pipeline research-to-article \
  110. --sources https://example.com/a https://example.com/b \
  111. --title "Evidence review" --language zh-TW --audience "engineers"
  112. notebooklm-pipeline research-to-social \
  113. --sources https://example.com/a --platform threads --variants 3
  114. notebooklm-pipeline batch-digest \
  115. --rss https://example.com/feed.xml --max-entries 20 --qa-count 5
  116. notebooklm-pipeline generate-all \
  117. --files ./paper.pdf --types audio slides report mind-map \
  118. --output-dir ./output --artifact-concurrency 2
  119. ```
  120. `trend-to-content` requires a separately installed `trend-pulse` command. Override
  121. its executable safely with `TREND_PULSE_CMD`; the integration does not invoke a shell.
  122. Pipelines create drafts and local artifacts. They do not publish to social networks,
  123. CMS products, or other remote destinations.
  124. ## MCP server
  125. Start stdio mode for an MCP client:
  126. ```bash
  127. notebooklm-mcp
  128. ```
  129. Example configuration:
  130. ```json
  131. {
  132. "mcpServers": {
  133. "notebooklm": {
  134. "command": "uvx",
  135. "args": ["--from", "notebooklm-skill", "notebooklm-mcp"]
  136. }
  137. }
  138. }
  139. ```
  140. Available tools:
  141. - `nlm_create_notebook`, `nlm_list`, `nlm_delete`
  142. - `nlm_add_source`, `nlm_list_sources`
  143. - `nlm_ask`, `nlm_summarize`
  144. - `nlm_generate`, `nlm_download`, `nlm_list_artifacts`
  145. - `nlm_research`, `nlm_research_pipeline`, `nlm_trend_research`
  146. Notebook deletion requires `confirm=true`. HTTP mode binds only to loopback:
  147. ```bash
  148. notebooklm-mcp --http --host 127.0.0.1 --port 8765
  149. ```
  150. Do not expose HTTP mode directly to a network. If remote access is unavoidable, put
  151. it behind an authenticated TLS proxy and apply host-level access controls.
  152. ## Operating rules
  153. 1. Verify authentication before a long workflow.
  154. 2. Confirm sources were ingested; treat `partial` or failed source entries honestly.
  155. 3. Ask focused questions and retain returned citation metadata.
  156. 4. Use exact notebook and artifact IDs in repeated automation.
  157. 5. Use bounded source/artifact concurrency; generation is quota-sensitive.
  158. 6. Do not delete notebooks or overwrite output without explicit user intent.
  159. 7. Do not claim a draft was published; no publishing integration exists here.
  160. 8. Return the JSON result or a faithful summary, including partial failures.
  161. ## Exit codes and recovery
  162. - `0`: operation completed successfully.
  163. - `2`: invalid or ambiguous arguments.
  164. - `4`: authentication required.
  165. - `1`: upstream, network, generation, or other operational failure.
  166. - `130`: interrupted by the user.
  167. Common recovery:
  168. ```bash
  169. notebooklm-auth verify
  170. notebooklm-auth setup # missing or expired session
  171. notebooklm-skill list-artifacts --notebook NOTEBOOK_ID # inspect a timed-out job
  172. ```
  173. Use `notebooklm-skill --help`, `notebooklm-pipeline --help`, and the relevant
  174. 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.

  1. # notebooklm-skill
  2. > Source-grounded NotebookLM automation for terminals and AI agents.
  3. [![CI](https://github.com/claude-world/notebooklm-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/claude-world/notebooklm-skill/actions/workflows/ci.yml)
  4. [![PyPI](https://img.shields.io/pypi/v/notebooklm-skill)](https://pypi.org/project/notebooklm-skill/)
  5. [![Python](https://img.shields.io/pypi/pyversions/notebooklm-skill)](https://pypi.org/project/notebooklm-skill/)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  7. [繁體中文](README.zh-TW.md)
  8. `notebooklm-skill` gives humans and MCP clients one consistent interface for Google
  9. NotebookLM. It creates notebooks from URLs, raw text, and local files; asks grounded
  10. questions with citation metadata; completes fast or deep web research; and generates
  11. or downloads NotebookLM artifacts.
  12. The project is built on `notebooklm-py` 0.8.x and FastMCP 4 (MCP Python SDK 2.x),
  13. and includes:
  14. - a JSON-first core CLI;
  15. - five end-to-end research pipelines;
  16. - a 13-tool FastMCP server;
  17. - profile-aware authentication and Skill installers;
  18. - one shared compatibility layer, so CLI, pipelines, and MCP use the same behavior.
  19. > This is an unofficial integration with NotebookLM's web API. Google can change the
  20. > service, availability, quotas, or artifact behavior without notice.
  21. ## Requirements
  22. - Python 3.10 or newer (CI covers 3.10 through 3.15)
  23. - a Google account with access to NotebookLM
  24. - Chromium for the one-time browser login (installed by `./install.sh`), or a local
  25. Google Chrome or Microsoft Edge
  26. - optional: the `trend-pulse` command for trend workflows, and `ffmpeg` plus Poppler
  27. for `scripts/make_video.sh`
  28. ## Quick start
  29. ### Isolated source install
  30. The installer creates a dedicated virtual environment, installs Chromium, links five
  31. commands into `~/.local/bin`, and installs the Claude Code Skill using the standard
  32. directory layout.
  33. ```bash
  34. git clone https://github.com/claude-world/notebooklm-skill.git
  35. cd notebooklm-skill
  36. ./install.sh
  37. notebooklm-auth setup
  38. notebooklm-skill list
  39. ```
  40. Ensure `~/.local/bin` is on `PATH`.
  41. ### PyPI or uvx
  42. ```bash
  43. # Persistent virtual environment
  44. python3 -m venv .venv
  45. source .venv/bin/activate
  46. python -m pip install notebooklm-skill
  47. python -m playwright install chromium
  48. notebooklm-auth setup
  49. # Or run without a persistent install
  50. uvx --from notebooklm-skill notebooklm-auth setup
  51. uvx --from notebooklm-skill notebooklm-skill list
  52. ```
  53. Direct upstream login is also available:
  54. ```bash
  55. uvx --from notebooklm-py notebooklm login
  56. ```
  57. Sessions are profile-aware. Select one with `--profile NAME` before a CLI
  58. subcommand, or set `NOTEBOOKLM_PROFILE`.
  59. To use the locally installed Google Chrome instead of bundled Chromium:
  60. ```bash
  61. notebooklm-auth setup --browser chrome --fresh
  62. ```
  63. ## Core CLI
  64. All successful commands print structured JSON to stdout. Diagnostics go to stderr;
  65. authentication errors return exit code 4 and argument errors return exit code 2.
  66. ```bash
  67. # Mixed-source ingestion with truthful per-source outcomes
  68. notebooklm-skill create \
  69. --title "Research" \
  70. --sources https://example.com/article \
  71. --files ./paper.pdf \
  72. --text-sources "Interview notes" \
  73. --strict
  74. notebooklm-skill ask \
  75. --notebook "Research" \
  76. --query "Which conclusions have the strongest evidence?"
  77. notebooklm-skill research \
  78. --notebook "Research" \
  79. --query "Recent independent evaluations" \
  80. --mode deep --max-sources 10
  81. notebooklm-skill generate \
  82. --notebook "Research" \
  83. --type slides --lang zh-TW \
  84. --output ./output/deck.pptx --output-format pptx
  85. notebooklm-skill list-artifacts --notebook "Research" --type slides
  86. ```
  87. Commands resolve an exact ID, unique title, or unique title substring. Use IDs for
  88. repeatable automation. Deletes require `--yes`; downloads refuse existing files or
  89. symlinks unless an explicit safe overwrite is requested with `--force`.
  90. ### Artifact types
  91. | Type | Default download | Notes |
  92. |---|---:|---|
  93. | `audio` | M4A | deep-dive, brief, critique, or debate |
  94. | `video` | MP4 | explainer, brief, or vertical short; multiple visual styles |
  95. | `cinematic` | MP4 | cinematic video workflow |
  96. | `slides` | PDF | PDF or PPTX |
  97. | `report` | Markdown | briefing, study guide, blog, or custom |
  98. | `study-guide` | Markdown | report shortcut |
  99. | `quiz` | JSON | JSON, Markdown, or HTML; fewer, standard, or more questions |
  100. | `flashcards` | JSON | JSON, Markdown, or HTML; fewer, standard, or more cards |
  101. | `mind-map` | JSON | immediate generation result |
  102. | `infographic` | PNG | orientation, detail, and style options |
  103. | `data-table` | CSV | structured extraction |
  104. Use `notebooklm-skill generate --help` for the live option matrix. Long-running
  105. generations support `--no-wait`, and later downloads can select `--artifact-id`.
  106. ## Pipelines
  107. ```bash
  108. notebooklm-pipeline research-to-article \
  109. --sources https://example.com/a https://example.com/b \
  110. --title "Evidence review" --audience "engineers"
  111. notebooklm-pipeline research-to-social \
  112. --files ./brief.pdf --platform linkedin --variants 3
  113. notebooklm-pipeline batch-digest \
  114. --rss https://example.com/feed.xml --max-entries 20 --qa-count 5
  115. notebooklm-pipeline generate-all \
  116. --files ./paper.pdf --types audio slides report mind-map \
  117. --output-dir ./output --artifact-concurrency 2
  118. ```
  119. `trend-to-content` requires the optional `trend-pulse` command. Pipelines return
  120. drafts and local artifacts; they do not publish to social platforms or remote CMSs.
  121. ## MCP server
  122. The default stdio transport is suitable for Claude Code, Cursor, and other MCP
  123. clients:
  124. ```json
  125. {
  126. "mcpServers": {
  127. "notebooklm": {
  128. "command": "uvx",
  129. "args": ["--from", "notebooklm-skill", "notebooklm-mcp"]
  130. }
  131. }
  132. }
  133. ```
  134. The 13 tools cover notebook CRUD, mixed sources, grounded chat, summaries, artifact
  135. generation/list/download, full research lifecycles, research pipelines, and trend
  136. research. Notebook deletion requires `confirm=true`.
  137. Optional HTTP mode is deliberately loopback-only:
  138. ```bash
  139. notebooklm-mcp --http --host 127.0.0.1 --port 8765
  140. ```
  141. Do not expose it directly to a network. See [SECURITY.md](SECURITY.md).
  142. ## Additional commands
  143. | Command | Purpose |
  144. |---|---|
  145. | `notebooklm-auth` | Setup, verify, or clear a selected auth profile |
  146. | `notebooklm-install-skill` | Install `SKILL.md` for a user or project, with safe backups |
  147. ```bash
  148. notebooklm-install-skill --scope project
  149. notebooklm-auth --profile work verify
  150. ```
  151. ## Development
  152. ```bash
  153. python3 -m venv .venv
  154. source .venv/bin/activate
  155. python -m pip install -e '.[dev]'
  156. ruff check .
  157. ruff format --check .
  158. mypy scripts mcp_server
  159. pytest --cov --cov-report=term-missing
  160. python -m build
  161. twine check dist/*
  162. ```
  163. More detail: [setup guide](docs/SETUP.md), [Skill instructions](SKILL.md),
  164. [API compatibility notes](references/api_surface.md), and [changelog](CHANGELOG.md).
  165. ## License
  166. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.