Content & Media Creation · teng-lin/notebooklm-py
notebooklm-python
Install, authenticate, troubleshoot, and operate Gemini Notebook through the notebooklm-py CLI or typed async Python API. Use for notebook and source management, grounded chat and research, and artifact generation or download when the user mentions Gemini Notebook, notebooklm-py, the notebooklm CLI, or its Python API. Do not use for the generic Gemini API or unrelated content creation.
L5 Restricted · Isolated sandbox & strict auditV2 Human-AuditedCredential / SessionExecute CommandInstall DepsNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
SKILL.md itself is not an executor, but an "agent operations manual": it instructs agents on how to invoke the `notebooklm` CLI packaged with the distribution, while the actual network and protocol implementations reside in the Python package (Web uses batchexecute RPC, alongside an Android gRPC backend).
SKILL.md
Use the `notebooklm` CLI for agent workflows. Prefer `--json` and explicit IDs so every operation is inspectable and safe under concurrency.
Implementation evidence is in the package: `src/notebooklm/rpc/types.py:94` defines `BATCHEXECUTE_URL = f"{DEFAULT_BASE_URL}/_/LabsTailwindUi/data/batchexecute"`, while `src/notebooklm/_env.py:22` defines `DEFAULT_BASE_URL = "https://notebook.google.com"`. This means every command invoked by the agent ultimately becomes a call to Google's undocumented RPC endpoints—SKILL.md governs "how to use it, what constitutes completion, and what strictly requires prior user confirmation", while the Python package handles "how to transmit the request".
This skill is an artifact packaged directly inside the Python distribution: during build time, SKILL.md from the repository root is injected into `notebooklm/data/SKILL.md`, and `notebooklm skill install` writes it to the agent host's skill directory, ensuring the skill text and CLI version naturally share the same source and version.
pyproject.toml
force-include = {"SKILL.md" = "notebooklm/data/SKILL.md", "AGENTS.md" = "notebooklm/data/CODEX.md"}
Installation target paths are specified in `src/notebooklm/_app/skill.py:50-51`: `"claude": SkillTarget("Claude Code", Path(".claude") / "skills" / "notebooklm" / "SKILL.md")` and `"agents": SkillTarget("Agent Skills", Path(".agents") / "skills" / "notebooklm" / "SKILL.md")`. The CLI also provides `--scope project|user`, `--dry-run`, `--no-clobber`, `--force`, `skill package` (to bundle uploadable archives), and `skill status --json` (reporting installed versions and `content_mismatch`). The closing section of SKILL.md explicitly states: "`notebooklm skill install` installs or updates supported local skill targets."
Authentication follows a "plaintext credential file + tiered authorization" model: browser login yields storage_state.json (session cookies), headless scenarios use master_token.json (account-level credentials), both enforce 0600 permissions (0700 for directories), and profile isolation is supported.
SKILL.md
A master token is a durable full-account credential that survives password changes; use a dedicated account, protect it in a secret store and as `0600` on disk, and explicitly revoke it if exposed.
On-disk locations and permissions are detailed line-by-line in the SECURITY.md table (e.g., `profiles/<profile>/storage_state.json` = Google session cookies / `0o600`; `profiles/<profile>/master_token.json` = Google master token (Android / headless) / `0o600`; `profiles/<profile>/browser_profile/` / `0o700`), enforced in code by `src/notebooklm/_atomic_io.py:221` ("``fchmod`` the temp file to ``mode`` (default ``0o600`` — cookies are …"). SKILL.md also specifically reminds that `NOTEBOOKLM_MASTER_TOKEN_JSON` in CI is merely a "secret transport convention" and must be written as a 0600 file before being unset.
It turns an unreliable asynchronous generation process into a verifiable state machine using "explicit IDs + readiness gates": sources must wait until `ready`, artifacts must wait until `completed`, and both must rely on the returned actual IDs rather than "the latest visible one".
SKILL.md
After adding sources, retain every `.source.id`, then run `source wait` for each before chat or generation.
Accompanying discipline: "Download that exact artifact with `-a <artifact_id> -n <notebook_id>`; never select the latest visible artifact."; status states are defined in the Output and Citations section (sources: `unknown`/`preparing`/`processing` -> `ready` or `error`; artifacts: `pending`/`in_progress` -> `completed`, `failed`, or `removed`).
Concurrency safety is achieved via triple isolation: each CLI command explicitly includes `-n/--notebook`, each concurrent run uses an isolated profile, and deep research uses `--run-id`; sharing a single writable storage_state.json across agents is strictly prohibited.
SKILL.md
For every concurrent run, also set a unique `NOTEBOOKLM_PROFILE=agent-<id>` so context and profile writes are isolated.
The same rule notes: "A new profile has no credentials: put a `master_token.json` copy in that profile and mint its storage before use. Never share one writable `storage_state.json` across agents."; in code, this corresponds to the dedicated lock for `storage_state.json` (`.storage_state.json.lock`) in `src/notebooklm/_atomic_io.py`—which explicitly rejects routing this filename through the generic atomic write path ("``atomic_update_json`` rejects ``storage_state.json`` paths").
Authorization boundaries are formulated as a strict contract rather than a slogan: safe read-only operations can proceed directly, but destructive, time-consuming, or disk-writing actions require explicit prior user confirmation; the rule also clarifies that "CLI lack of prompts ≠ authorization granted".
SKILL.md
User intent, not the presence of a CLI prompt, is the authorization boundary.
The checklist requiring prior confirmation includes deletion operations (notebook/source/note/artifact/label/profile deletion, sharing removal, logout, clear, research cancellation, `ask --new`), `language set` (which alters global account output language), generation and long waits, downloads (writing files), `research wait --import-all` (importing sources), and `ask --save-as-note` along with `history --save` (creating notes). A read-only toggle is provided for diagnosis: "Add `--passive` when the check must be strictly read-only".
Citations are fully traceable: chat responses include `references[].source_id`, and character offsets are UTF-16 offsets (not flat byte/character offsets of the body text), with dedicated parsing functions provided rather than leaving slicing to the agent.
SKILL.md
A reference's `start_char`/`end_char` are UTF-16 offsets into the structured source document, not flat `SourceFulltext.content`.
Accompanying API: "In Python, use `from notebooklm import resolve_chat_reference_passage`, then call `await resolve_chat_reference_passage(client, notebook_id, reference)`; it uses the exact document range and falls back to `find_citation_context()` when necessary."—encapsulating error-prone offset conversions into the library instead of leaving the agent to guess.
Failure handling provides deterministic exit codes and structured envelope contracts rather than vague prompts: 0 for success, 1 for general failure, 2 for `source wait` timeouts, and 1 for `artifact wait`/`research wait` timeouts, requiring initial read-only diagnosis without mutating state during checks.
SKILL.md
Exit 0 means success. Expected command failures use exit 1. A `source wait` timeout uses exit 2; `artifact wait` and `research wait` timeouts use exit 1.
The same section distinguishes two JSON envelope shapes ("Ordinary handled JSON failures use `{error, code, message}`, while wait commands return domain envelopes such as `{"status": "timeout", "error": "..."}`"), mandates using only the specified read-only diagnostic commands, and warns against infinite retries on generation failure ("do not loop indefinitely").
2Core Capabilities
01Full lifecycle management of Notebooks and sources (list/create/add sources/wait for readiness), supporting various source types including URLs, YouTube, Google Drive, text, and files
02Grounded chat based on sources, returning conversation_id and locatable citations
03Generation of 9 artifact types: audio, video, slide-deck, infographic, report, mind-map, data-table, quiz, flashcards
04Two-phase deep research orchestration: non-blocking initiation (`--mode deep --no-wait`) → explicit authorization followed by `research wait --import-all` to import as sources
05Targeted artifact download by ID to user-specified paths (supports `--all`, conflict resolution, and dry-run)
06Dual programming interfaces: CLI (`--json` structured output) + typed async Python API (`NotebookLMClient.from_storage()` with namespaces: notebooks/sources/chat/research/artifacts/mind_maps/notes/settings/sharing/labels/collections)
07Four authentication pathways: browser OAuth login, browser cookie extraction (`--browser-cookies <browser>`), master-token headless authentication, and CI environment variable JSON
08Multiple frontends sharing the same business core: Click CLI, FastMCP MCP server (including remote/OAuth transport), FastAPI REST server, and Android gRPC backend
09Self-installation and validation: installs this SKILL.md into `.claude/skills/notebooklm/SKILL.md` or `.agents/skills/notebooklm/SKILL.md`, can bundle uploadable archives, and reports installed versions and content drift
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | notebooklm CLI（本包 entry point，agent 全程调用它） |
| cli | pip / uv tool install / pipx（安装包本体，可选 extra 决定能力面） |
| cli | uv / uvx（桌面版 MCP 扩展启动器，用于拉起 notebooklm-mcp） |
| network | NotebookLM Web batchexecute RPC 端点（默认 notebook.google.com，可切 notebooklm.google.com / 企业域） |
| network | Google 账户与 OAuth 端点（浏览器登录 / master token 换取 / 令牌校验） |
| network | Google Drive 导入下载端点（加 Drive 源时拉文件） |
| network | Google APIs（Android 后端 Drive 暂存上传与请求） |
| api | gpsoauth（无头 master-token 认证，换取 Google 会话 cookie） |
| package | 运行时依赖 httpx / click / rich / filelock |
| package | 可选 extra：browser(playwright) / cookies(rookie-cookies) / headless(gpsoauth) / impersonate(curl_cffi) / android(grpcio+protobuf) / mcp(fastmcp==3.4.2) / server(fastapi+uvicorn+python-multipart) / markdown(markdownify) |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Isolated environment, per-use explicit authorization
For Administrators
Strict authorization, full audit, compliance signoff
Evidence & Triggers (File Paths & Excerpts)
- 本地凭据 / 浏览器配置: Reads user login cookies/sessions/keyrings: `~/.notebooklm/profiles/<profile>/storage_state.json` (Google session cookies; default p
- scripts/: Executes local scripts or commands: SKILL.md instructs agents to execute `pip install "notebooklm-py[browser]"` / `[c` in the host shell
- scripts/ 或 SKILL.md: Declares dynamic installation of external language package dependencies
- 网络端点: Declares external network access: https://notebook.google.com/_/LabsTailwindUi/data/batchexecute (default Web RPC; can
- 本地工作目录: File read/write and artifact output: downloads artifacts to user-specified paths (`notebooklm download <type> <path> -n <nb> -a <artifact>`), SKI
Audit Notes: and verify its operational boundaries. Criterion: This is not a prompt-only skill—it distributes substantial real code (530 Python files), performs network RPCs, reads account-equivalent credentials (storage_state.json / master_token.json / browser cookie stores), writes files upon user instructions (artifact downloads, installing SKILL.md to .claude/skills), and offers optional components to expose credentialed services publicly via MCP/REST + Tailscale Funnel. Reason for not rating Orange/Red: Although its operational footprint is broad, it is explicitly constrained—authorization boundaries (destructive actions/disk writes/long waits/`language set`/`--import-all` require prior user confirmation; "prompt absence is not consent"), permission masks (0600/0700), atomic writes, read-only diagnostic switch `--passive`, exit code contracts, and SECURITY.md operator threat models and disclosure workflows are all present in the repository, along with clear disclaimers regarding its unofficial status with Google services. Key reasons for rating Yellow rather than Green: credentials operate at the account level and can be invalidated by password change if lost; and there is an absence of isolation mechanisms against "source document content injection" (see injection_surface). If the user exposes MCP/REST to the public network, it should be treated as Orange (anyone accessing the process effectively holds full NotebookLM permissions for that Google account).
5Second-Pass Verification
- [ok] skill.path 定位 — 候选位置检查：仓库根有 SKILL.md（存在，314 行）；无 skills/ 目录、无 .claude/skills/、无 plugins/；另在包内发现它的分发副本位置 `notebooklm/data/SKILL.md`（构建期注入，非仓库源文件）。故按批次规则 path='.'。
- [ok] 『实现方式』核对：SKILL.md 是不是空壳？（first-pass 假设它靠 CLI） — 不是空壳也不是纯文档——它是 crate 级薄指令 + 重实现库的组合：SKILL.md 里所有命令都能在包里找到对应实现（entry points 三个 console script；download 逻辑见 _app/download.py 的 'Click-free core' 说明），且 pyproject 的 force-include 把 SKILL.md 本身当包数据分发，说明二者版本绑定。没有夸大口径：它自称的前提（Python 3.10+、需 pip 装包、非官方集成）都在源码/文档里有对应。
- [ok] 外部依赖逐条复核（第二遍独立重查调用点） — 8 条 external_deps 全部在源码中找到调用点或声明点，无一条来自『推测』：CLI/uvx 来自 SKILL.md 与 desktop-extension；网络四条来自 rpc/types.py、_env.py、_web/sources/drive_import.py、_source/drive.py 的常量；gpsoauth 与各 extra 来自 _auth/mint_service.py 与 pyproject.toml。
- [ok] 安全结论反例搜索：有没有漏掉的网络调用/隐藏脚本/混淆内容？ — 按主机名穷举后未发现第三方（非 Google）外发；未发现混淆代码或 base64 载荷；`src/notebooklm/_android/proto/**` 是 Google 生成的 protobuf 桩（自动生成、量大但非隐藏逻辑）；desktop-extension/run_server.py 只做 uvx 定位与 exec，且注释明确 stdout 必须保持纯 JSON-RPC（有单测暴露函数）。deploy/ 与 MCP/REST 是 opt-in 且 SECURITY.md 把风险写明。
- [ok] injection_surface 的『无隔离条款』是否有遗漏的防护（例如源内容白名单/沙箱） — 在 SKILL.md 全文检索注入/不可信相关内容：仅有针对自身权限的授权边界（'User intent, not the presence of a CLI prompt, is the authorization boundary.'）与凭证不外泄要求（'Never expose credential contents.'），没有任何把源文档/回答内容当不可信指令的条款；包侧对 Drive 下载做了域名白名单（_TRUSTED_GOOGLE_DOMAINS）与 URL 校验，但那是传输安全，不是内容注入防护。故 first-pass 的判断成立，且已把风险写进 risks。
- [ok] 退出码/状态取值等细节表述是否与代码一致 — SKILL.md 所述 exit 0/1/2 与 JSON 包络形态来自仓库自述的契约文档（docs/cli-exit-codes.md 同主题）；本次未逐条跑 CLI 实测（不构造账号环境、也不跑测试），故只按『源码文本一致』给结论，未验证运行时行为。
- [ok] 元数据复核 — 本地 HEAD 等于 pin；LICENSE 为 MIT，pyproject `license = {text = "MIT"}` 与 classifiers 'License :: OSI Approved :: MIT License' 一致；stars 19330、last_push 2026-09-13、license MIT 取自池内 queue-100.json（未额外 gh 复核）。installs 无公开来源，置 null。
6Verdict & Scenarios
Best for: Ideal for workflows driving NotebookLM via natural language: turning collections of links, PDFs, and Drive documents into summaries, podcasts, videos, slide decks, mind maps, and quizzes; suited for using NotebookLM as a deep research assistant and exporting results locally; developers can integrate directly via the typed async Python API or plug it into agent architectures via MCP/REST; multi-agent concurrent environments benefit from clear profile/ID isolation conventions.
Not for: Not suitable as an "account-free public tool"—it requires a real Google account and active service permissions (some generation types require Google AI Ultra), and relies on an unofficial integration of undocumented APIs that may break at any time. Not suitable for strict compliance and audit environments (plaintext credential storage + undocumented RPCs + single-tenant MCP/REST do not meet enterprise multi-tenant standards). Not suitable for public exposure to untrusted users (equivalent to sharing account privileges). Not suitable for users who only require generic Gemini API calls—SKILL.md explicitly states: "Do not use for the generic Gemini API or unrelated content creation."
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload notebooklm-python.tar.gz
sha256:
Option B · Copy Guide for Agent2231081c4d43c0ea…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 5472d7cfcc.