Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[Unreleased]

[0.7.2] - 2026年06月08日

Added

• ChatGPT File Parameter Upload Bridge (PR #220) — Enables direct upload of files provided by ChatGPT App/Action clients by resolving and downloading from the client's temporary HTTPS URL before uploading to Google NotebookLM. Thanks to @insane66613 !
• ChatGPT Artifact Download Bridge (PR #220) — Allows copying generated artifacts to the local server's public directory and returning public download links when the server runs behind secure tunnels. Exposes a new /artifacts/{filename} route in the MCP HTTP server. Thanks to @insane66613 !
• Transient Source Content Polling (poll_source_content service function) — Automatically handles Google NotebookLM indexing states (processing, indexing, try again) via robust polling with exponential backoff when fetching raw source contents immediately after creation.

Fixed

• Sanitize no_proxy environment variable (PR #221) — Fixed package import crashes on Windows systems by cleaning up the no_proxy environment variable on initialization before httpx parses it. Thanks to @insane66613 !
• Modern Chrome Cookie DB path detection (PR #222) — Improved the SQLite cookie database location search logic for Google Chrome to work correctly with modern Chrome setups. Thanks to @insane66613 !
• Profile-aware headless refresh (PR #223) — Fixed headless login refresh to use the default/active profile configured in the CLI configuration file instead of falling back. Thanks to @insane66613 !
• AuthHealthChecker API fallback passed wrong cookie format, causing false stale on semi-stale sessions (PR #225) — The API fallback flattened profile.cookies to a dict, dropping domain-specific duplicates and omitting session_id / build_label. The API probe now passes profile.cookies unchanged with all session fields, matching nlm login --check. Thanks to @insane66613 !
• server_info, refresh_auth, and studio_create disagreed on semi-stale auth (PR #225, Fixes #224) — These three MCP paths each ran independent auth checks, so server_info could report stale and studio_create refuse to run while notebook_list and CLI tools worked fine. All MCP auth gates now share credentials_are_usable() (AuthHealthChecker + live API confirmation), eliminating split-brain results. Thanks to @insane66613 !

[0.7.1] - 2026年06月06日

Fixed

• server_info reported "stale" for valid semi-stale cookies (PR #219) — Google enforces different session lifecycles for the NotebookLM homepage (a navigation endpoint) and the RPC API endpoints. Cookies that are "semi-stale" — rejected by the homepage with a redirect to accounts.google.com, but still 100% accepted by the RPC API — were causing the MCP server_info tool (and nlm login --check) to falsely report "stale" even though every actual API tool would work fine. The new AuthHealthChecker runs a homepage probe first and, on expired / http_401 / http_403, falls back to a live NotebookLMClient.list_notebooks() call before deciding. The homepage headers were also upgraded to use the full browser-like _PAGE_FETCH_HEADERS (including Sec-Fetch-Dest / Sec-Fetch-Mode / Sec-Fetch-Site / Sec-Fetch-User) — without them Google was bot-detecting the homepage check and redirecting even fresh cookies, producing false "stale" reports on first probe. Results are cached for 30 seconds with mtime-based bypass, so an external nlm login is reflected without waiting for the TTL. The CLI and MCP now share the cache via the get_auth_health_checker() singleton in services/auth.py. Thanks to @SERDAR-AKIN for the original multi-probe design and PR #219!

Changed

• AuthHealthChecker lives in services/auth.py, not core/auth.py — the multi-probe orchestration, 30-second cache, and verdict aggregation are business logic and belong in the services layer per the layering rule in CLAUDE.md / AGENTS.md / GEMINI.md. core/auth.py stays focused on the low-level auth primitives (AuthManager, AuthTokens, check_auth, save_tokens_to_cache, load_cached_tokens, _fetch_notebooklm_homepage).
• server_info docstring no longer calls auth_status a "live check" — it is cached for 30 seconds with mtime-based bypass. docs/AUTHENTICATION.md documents the same contract for nlm login --check (always live) vs server_info (cached).
• AuthHealthReport.valid is now verdict == "configured" (was !=) — the field was inverted: it returned True for stale / unverified / not_configured reports. Pinned by TestReportValid in tests/services/test_auth_health.py.
• API-probe exceptions are classified as transport errors when they are — _probe_api now catches httpx.TimeoutException and httpx.RequestError explicitly and emits the "network_error:" prefix so _determine_verdict can route them to "unverified". Previously all exceptions emitted f"{type(e).__name__}: {e}", which meant a real transport error on the API path was misclassified as an auth failure ("stale"). Pinned by TestProbeApiErrorClassification in tests/services/test_auth_health.py.

[0.7.0] - 2026年06月03日

Added

• Studio prompting guide and fast-track agent behavior — AI agents using the MCP skill now follow a fast-track prompting model: infer format, style, and prompt from context, emit a one-line notice, and generate immediately — no multi-question intake questionnaires. A guided preview mode (show settings + full prompt before generating) kicks in only for vague requests, high-stakes content (e.g. cinematic video), or when the user explicitly asks. Two new reference documents ship with the skill: references/studio-prompting-guide.md (per-artifact decision trees, prompt parameters) and references/studio-prompt-examples.md (copy-paste templates). SKILL.md and workflows.md updated throughout.
• Cinematic video format — video_format=cinematic is now documented and supported in the skill, CLI, and MCP guide. Cinematic videos take the full creative brief via focus_prompt / --focus; --style is not applicable.

Fixed

• Query returns thinking step instead of short answer (Issue #214) — When the AI's final answer was under 20 characters, for example ANSWER: C from a multiple-choice prompt, nlm discarded it and returned the longest thinking chunk instead. The 20-char guard in _extract_answer_from_chunk (both the list-form and string-form branches) was redundant with the existing type indicator at first_elem[4][-1] (1 = answer, 2 = thinking), which is the authoritative discriminator. Removed both guards. The type indicator still routes short thinking chunks to the thinking bucket, so behavior for normal answers is unchanged. 4 new regression tests in TestShortAnswerRegression cover: short answer wins over a longer thinking chunk, single-character answers, short thinking chunks still filtered as thinking, and the string-form first_elem path.
• nlm notebook create missing --json (Issue #215) — Every other notebook verb (list, get, describe, query) already supported --json, but create did not. This was a real friction point for agent workflows that need to capture the new notebook ID reliably. Added the flag; the output is the same notebook_id / title / url / message dict that other verbs return, so scripting just works. Thanks to @SimonMallas for the report and end-to-end test in the issue!
• auth_status = "stale" was misleading (Issue #215) — The MCP server_info tool (and nlm login --check) reported "stale" for any non-configured / non-not_configured outcome, which silently grouped three very different conditions together: (a) credentials are actually expired and operations will fail, (b) the live check hit a network error/timeout/non-200 and cached creds may still work, and (c) the saved profile failed to load. The new state machine splits this into two distinct values: "stale" is reserved for cases (a) and (c) where the user genuinely needs to nlm login, and a new "unverified" reports case (b) so agents don't pester users to re-auth on transient network blips. Unknown future reasons stay conservative ("stale"). No raw AuthCheckResult.reason strings are exposed; only the 5 stable status values. The new Understanding auth_status section in docs/AUTHENTICATION.md documents each state and what to do.
• format_item silently discarded plain-dict results — All three formatter classes (TableFormatter, JsonFormatter, CompactFormatter) checked for model_dump / __dict__ before isinstance(item, dict). Because TypedDict instances are plain dict at runtime (no model_dump, no per-instance __dict__ in CPython), they fell through to the worst-case path: JsonFormatter wrapped the payload as {"value": {...}} instead of printing it flat, and CompactFormatter emitted str(item) (the raw dict repr) instead of the notebook ID. Fixed by adding isinstance(item, dict) as the first branch in all three format_item methods. nlm notebook create --json and pipe capture now work correctly.
• HTTP 401/403 misclassified as "unverified" in server_info — The reason.startswith("http_") catch-all in _check_auth_status mapped every non-200 response — including definitive credential-rejection codes 401 and 403 — to "unverified" ("cached credentials may still work, do not prompt re-auth"). Added explicit http_401 / http_403 → "stale" guards before the general http_ branch so agents correctly prompt re-authentication when cookies are genuinely rejected by NotebookLM.

Documentation

• **New docs/GETTING_STARTED.md guid...

Contributors

• @byingyang
• @ildella
• @NOirBRight
• @kylebrodeur
• @meirtsvi
• @laofun
• @cbruyndoncx
• @beausea
• @rujinlong
• @agarwalvipin
• @pjeby
• @maxcanada
• @pan-long
• @cowhi
• @adlewis82
• @Neophen
• @stanleykao72
• @nikosavola
• @insane66613
• @latuannetnam
• @mdshearer
• @nickyfoto
• @derekszen
• @sjs33
• @abanoub-ashraf
• @danielbrodie
• @Le-Yann
• @JumpLao
• @davidszp
• @argonaut-cm
• @olaservo
• @Carlos-OL
• @mateogon
• @SERDAR-AKIN
• @Premshay
• @ahmelkholy
• @irvinghu07
• @kmfb
• @ahnbu
• @woohyun212
• @SimonMallas
• @Amy-Ra-lph
• @Victor777777
• @casjogreen
• @devnull03
• @Robiton
• @saitrogen
• @andrepreira
• @pakulyaev
• @997unix
• @eng-M-A-AbelLatif
• @sebsnyk
• @fabianafurtadoff
• @theteleporter
• @CryptoWombat
• @ojsed
• @swiezaczek
• @josuebustosn
• @wccheung11011001
• @responsiblefleet
• @mylaser215
• @zxyasfas
• @jonathanzhan1975
• @tody-agent
• @MinhDung2209
• @sickn33
• @ovai-felix
• @guia-matthieu
• @SKMKZP
• @nobolso
• @idankatz64-commits
• @nikolaykazakovvs-ux
• @m3saros

v0.7.1 — 2026年06月06日

Fixed

• server_info reported "stale" for valid semi-stale cookies (PR #219) — Google enforces different session lifecycles for the NotebookLM homepage (a navigation endpoint) and the RPC API endpoints. Cookies that are semi-stale — rejected by the homepage with a redirect to accounts.google.com, but still 100% accepted by the RPC API — were causing the MCP server_info tool (and nlm login --check) to falsely report "stale" even though every actual API tool would work fine. The new AuthHealthChecker runs a homepage probe first and, on expired / http_401 / http_403, falls back to a live NotebookLMClient.list_notebooks() call before deciding. The homepage headers were also upgraded to use the full browser-like _PAGE_FETCH_HEADERS (including Sec-Fetch-Dest / Sec-Fetch-Mode / Sec-Fetch-Site / Sec-Fetch-User) — without them Google was bot-detecting the homepage check and redirecting even fresh cookies, producing false "stale" reports on first probe. Results are cached for 30 seconds with mtime-based bypass, so an external nlm login is reflected without waiting for the TTL. The CLI and MCP now share the cache via the get_auth_health_checker() singleton in services/auth.py. Thanks to @SERDAR-AKIN for the original multi-probe design and PR #219!

Changed

• AuthHealthChecker lives in services/auth.py, not core/auth.py — the multi-probe orchestration, 30-second cache, and verdict aggregation are business logic and belong in the services layer per the layering rule in CLAUDE.md / AGENTS.md / GEMINI.md.
• server_info docstring no longer calls auth_status a live check — it is cached for 30 seconds with mtime-based bypass. docs/AUTHENTICATION.md documents the same contract.
• AuthHealthReport.valid is now verdict == "configured" (was !=) — the field was inverted: it returned True for stale / unverified / not_configured reports. Pinned by TestReportValid.
• API-probe exceptions are classified as transport errors when they are — _probe_api now catches httpx.TimeoutException and httpx.RequestError explicitly and emits the "network_error:" prefix so _determine_verdict can route them to "unverified". Pinned by TestProbeApiErrorClassification.

Credits

Thanks to @SERDAR-AKIN for the original multi-probe health checker design and PR #219.

Contributors

• @SERDAR-AKIN

What's new

Added

• Studio fast-track agent behavior — AI agents now infer format, style, and prompt from context and generate immediately. No intake questionnaires. Two new reference docs ship with the skill: studio-prompting-guide.md and studio-prompt-examples.md.
• Cinematic video format — video_format=cinematic is now fully documented and supported. Pass the full creative brief via focus_prompt / --focus.

Fixed

• nlm notebook create --json — Output was silently wrapped as {"value": {...}} instead of a flat dict. Fixed across all three formatter classes.
• HTTP 401/403 misclassified as "unverified" — Credential rejections now correctly map to "stale" so agents prompt re-auth instead of assuming creds still work.
• auth_status = "stale" was misleading — Transient network failures now return "unverified" (retry later) instead of "stale" (go re-auth). See docs/AUTHENTICATION.md for the full state table.
• nlm notebook create missing --json — Added parity with all other notebook verbs. Thanks @SimonMallas !
• Query returning thinking chunk instead of short answer — Removed the redundant 20-char guard that discarded short answers like ANSWER: C.

Documentation

• New docs/GETTING_STARTED.md — install, login, agent registration, and migration guide from browser-automation–based NotebookLM MCPs.
• MCP_GUIDE.md server-naming note — avoid name collisions with legacy MCPs.

Full changelog: https://github.com/jacob-bd/notebooklm-mcp-cli/blob/main/CHANGELOG.md

Contributors

• @SimonMallas

Highlights

This is a maintenance release. No new user-facing features, but a real bug got caught and fixed, plus the kind of internal cleanup that makes the next batch of features land faster.

Long-running MCP servers pick up new tokens immediately

If you run notebooklm-mcp as a persistent server, the 0.6.14 release added a 60-second cache around the auth check. Good for performance, bad in one specific case: if you ran nlm login to refresh tokens while the server was running, the server kept using the old tokens for up to 60 seconds after.

The fix watches the auth files on disk. As soon as nlm login writes fresh cookies to any profile, the server notices the file change and re-validates auth on the next call. No restart, no refresh_auth dance, no waiting for the TTL to expire.

If you run the CLI in a long agent loop, this also matters: an external nlm login (say, from a separate process or terminal) no longer leaves you stuck on stale tokens for a minute.

A bug in the bug fix, caught by live testing

The honest version: the first attempt at the mtime fix watched the wrong file. It looked at the legacy auth.json instead of the modern profiles/<name>/cookies.json layout that this project has used since the v0.3.0 multi-profile refactor. All 916 unit tests passed because the tests used a mocked file path. The bug only showed up when I ran the real flow: nlm login --profile personal --check (warms the cache), then nlm login --profile personal --force (rewrites the profile's cookies), then nlm notebook list (should use the new cookies but didn't, because the guard was watching a different file).

So the second iteration of the fix stats every cookies.json under profiles/, plus the legacy auth.json, and uses the max mtime. A write to ANY of them invalidates the guard, regardless of which profile the active session is using or which profile the config's default_profile points to.

This is exactly the kind of bug that hides behind green unit tests forever and only shows up in production. The fix is in. If you maintain a long-running MCP server, this is the release to upgrade to.

Internal cleanup: services layer for auth

Every cli/ and mcp/ file that needed check_auth, AuthManager, or related helpers used to import them directly from core/. The codebase has a layering rule (cli/ and mcp/ go through services/, never core/ directly) and 11 of those imports were breaking it. The 0.6.14 release fixed one of them. This release fixes the other 10.

services/auth.py is now a real shim with 7 exports: check_auth, load_cached_tokens, save_tokens_to_cache, get_cache_path, validate_cookies, plus the two class symbols AuthTokens and AuthManager (via PEP 562 __getattr__, which preserves isinstance checks and lets tests monkeypatch the core class without having to patch the re-export).

No behavior change for users. The point of the exercise is that when the next auth refactor lands, only the shim needs to change, not 11 call sites.

The only remaining direct core.auth import in cli/ or mcp/ is in utils/cdp.py, which has a circular-import guard and is intentionally outside the layering rule's scope.

Update

uv tool install --upgrade notebooklm-mcp-cli
# or
pip install --upgrade notebooklm-mcp-cli

Credits

No community PRs in this release. It was a me-and-the-test-suite affair. The unit tests passed on the first try. The integration test (which I wrote after shipping 0.6.14, prompted by your pushback on the prior fix) caught the real bug. This is what "test before shipping" is for, and I'm glad we did it.

Highlights

Auth finally tells the truth

You know that weird thing where the CLI says "Authenticated" but then the next API call fails anyway? Two PRs kill that flow:

• PR #211 by @insane66613 : nlm login no longer crashes when your existing auth is already expired. It used to throw an internal stack trace. Now it walks you through re-auth cleanly.
• PR #212 by @idankatz64-commits : When the auth check fails, studio tools used to return a fake status: success and let the API call surface a cryptic downstream error. Now they return status: error with a clear error_reason (expired, no_tokens, stale_heuristic, etc.) and tell you to run nlm login. Way easier to debug from an agent loop.

Long-lived MCP servers won't OOM anymore (Issue #213)

If you run notebooklm-mcp as a persistent server (Claude Code, long-lived stdio, anything that keeps the process alive across many chats) and hit multiple notebooks in parallel, the in-process conversation history cache used to grow without bound. After a few hours of heavy use, the process could eat a few GB of RAM.

Fix: bounded cache with three env-var knobs, all 0 = unlimited:

After a trim, turn_number renumbers to 1..N so the first turn is always turn_number=1. New get_conversation_cache_stats() exposes counts for monitoring. The 12 new tests cover the FIFO behavior, LRU promotion, env-var parsing (including negative values, which clamp to 0 with a warning), and the stats method's lock-release window.

Auth check cached for 60s

Every studio_create call used to re-validate auth over HTTP. That roundtrip adds up across a long agent run, especially on the CLI side. The new ca85fae commit caches the "auth is valid" result for 60 seconds, and the cache clears the instant auth flips to invalid. So you get the speedup without the stale-TTL trap. This is per-process, not per-profile, and resets cleanly on any auth failure.

Improved docs

The bundled SKILL.md (and the user-level nlm-skill) got a new Section 16: Long-Lived MCP Server Configuration covering all the new env vars, the --stateless flag (HTTP transport only, not a cache control as the name might suggest), the error_reason field, and the pre-flight auth behavior. If you run this as a server in production, read that section. There's also a new Error Recovery row for the login crash so agents know what to do when they see the new error shape.

Update

uv tool install --upgrade notebooklm-mcp-cli
# or
pip install --upgrade notebooklm-mcp-cli

Contributors

Huge thanks to @insane66613 (PR #211) and @idankatz64-commits (PR #212) for the auth fixes. Community PRs are the whole reason this project stays reliable. If you've been sitting on a bug report or a fix, the next release window is open.

Contributors

• @insane66613
• @idankatz64-commits

Security

• TOCTOU-safe credential file creation (PR #205) — All credential files (auth.json, cookies.json, metadata.json, port map) were previously written with default permissions and then chmod'd to 0o600 — leaving a brief window where the file was world-readable. Fixed using os.open() + os.fdopen() so the file descriptor is created with 0o600 from the start. Thanks to @Amy-Ra-lph for the PR and thorough implementation!
• HTTP and SSE external-bind enforcement — Running notebooklm-mcp --transport http --host 0.0.0.0 (or --transport sse) previously emitted a warning but still bound to the external address. The server now refuses to start unless NOTEBOOKLM_ALLOW_EXTERNAL_BIND=1 is explicitly set, preventing accidental cookie exposure on untrusted networks. The guard now covers both HTTP and SSE transports.
• GitHub Actions pinned to full commit SHAs (PR #207) — All four workflow files now pin third-party actions to their full 40-character commit SHAs with a version comment for readability. Prevents tag-drift supply chain attacks. Thanks to @Amy-Ra-lph for the careful SHA verification!

Fixed

• terminate_chrome() null-safety (PR #205) — On double-call, _cached_ws.close() could raise AttributeError. The reference is now captured before the try block. Thanks to @Amy-Ra-lph !
• Cookie key whitespace handling (PR #205) — Added .strip() to cookie key parsing in save_auth_tokens to handle edge cases with leading/trailing whitespace in cookie headers.
• Auth check consistency (PR #203) — Unified auth checking logic under a single check_auth() function with a typed AuthCheckResult, eliminating subtle differences between the MCP and CLI auth status paths. Thanks to @derekszen for the clean refactor!

Changed

• Exponential backoff for source reconciliation polling — _reconcile_source() now uses exponential backoff (1s → 2s → 4s) to reduce unnecessary API calls on slower operations.
• File path canonicalization for uploads — add_file() now calls .expanduser().resolve() so paths like ~/Documents/file.pdf work correctly and symlinks are fully resolved before validation.
• raw_response field removed from query() return — The field was never read by any caller. Removing it avoids leaking raw API response text into future serializers.

Update

uv tool install --upgrade notebooklm-mcp-cli
# or
pip install --upgrade notebooklm-mcp-cli

Contributors

• @derekszen
• @Amy-Ra-lph

Fixed

• Manual login Netscape cookie parser fixes (PR #199 / Issue #198) — Fixed three bugs in the Netscape/Mozilla cookie file parser used in nlm login --manual:
  • Resolved a critical bug that treated #HttpOnly_ lines as comment rows and silently ignored them, which dropped essential Google authentication cookies like __Secure-1PSIDTS and __Secure-3PSIDTS (resulting in cryptic 401 errors).
  • Allowed empty-value cookies to be parsed with a value of "" instead of being skipped by ensuring trailing tab characters are not stripped from the end of the line.
  • Hardened value extraction to defensively join tab-containing cookie values instead of truncating them.
  • Added 4 new test cases to prevent future regressions. Thanks to @pan-long for the comprehensive PR and excellent troubleshooting!
• MCP source_add tool and SKILL.md file-type alignment (PR #197) — Updated the source_add MCP tool docstring and the global SKILL.md guidelines to list all 18 supported file-type extensions (PDF, TXT, MD, DOCX, CSV, EPUB, MP3, M4A, WAV, AAC, OGG, OPUS, MP4, JPG, JPEG, PNG, GIF, WEBP) instead of a restricted subset. Also documented how image-bearing sources are ingested to feed the Studio video generation's visual-crop pipeline to generate on-screen aids in Video Overviews. Thanks to @Premshay for the excellent documentation enhancement and detailed research on the visual-crop pipeline!

Contributors

• @pan-long
• @Premshay

What's Changed

Fixed

• False-negative errors on source_add and research_import (Issue #196) — source_add (text, URL, Drive) and research_import were reporting errors even when NotebookLM had successfully accepted the source for async processing. Added a _reconcile_source() helper that polls the source list after a code 3 or 9 error to verify the actual outcome. Also eliminates a double-submission bug for URL sources on v1 RPC accounts. Thanks to @mdshearer for the detailed report!

• Snap Chromium profile directory (PR #195) — Fixed Exit code 21: Failed to create a ProcessSingleton for snap-installed Chromium on Ubuntu. Snap browsers are now detected and redirected to the snap-accessible profile path. Thanks to @ildella !

• Audio download 403 on cross-domain CDN (PR #193) — Fixed HTTP 403 from Google's audio CDN caused by incorrect Sec-Fetch-Site: none header. Now mirrors Chrome's window.open() header shape. Thanks to @responsiblefleet !

Full Changelog: https://github.com/jacob-bd/notebooklm-mcp-cli/blob/main/CHANGELOG.md

Contributors

• @ildella
• @mdshearer
• @responsiblefleet

Added

• Hermes Agent Support — nlm skill install hermes now installs the NotebookLM skill for Hermes Agent by NousResearch. Respects the $HERMES_HOME environment variable for custom install paths.

Fixed

• Windows Tool Detection — nlm skill install no longer falsely warns that tools are not installed on Windows.
• Windows Permission Errors — safe_mkdir now catches PermissionError and provides an actionable icacls fix command instead of a raw traceback.
• Windows Encoding Errors — All read_text() / write_text() calls now explicitly specify encoding="utf-8" to prevent UnicodeDecodeError on Windows systems that default to cp1252.
• CLI Studio Status Missing Mind Maps — nlm studio status now routes through the service layer so mind maps are included.

Changed

• Shared is_tool_on_system() helper, ToolConfig TypedDict, update-check crash guard.
• Updated file upload docs with complete supported formats list.

Full Changelog: v0.6.8...v0.6.9

Changes

• Fixed notebook query content-type issue to ensure compatibility with stricter backend validation.
• Updated version metadata across documentation and extension manifest.

Contributed by @fabianafurtadoff

Contributors

• @fabianafurtadoff