Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
Does Gemini Notebook MCP Cli need an API key?
No required environment variable is listed on this record.
What transport does Gemini Notebook MCP Cli use?
Gemini Notebook MCP Cli runs locally over stdio.
When was Gemini Notebook MCP Cli last checked?
Last checked 2026-11-08. โ Install, login, agent setup, and migration from another Gemini Notebook MCP. โ Complete command reference. โ All 53 MCP tools with examples
From the publisher
Documentation
Gemini Notebook (formerly Google NotebookLM) CLI & MCP Server
Programmatic access to Gemini Notebook โ via command-line interface (CLI) or Model Context Protocol (MCP) server.
๐จ New: Protected login storage (recommended)
Your saved Google login can now be encrypted, with its key kept in your computer's keychain instead of a plain file. We highly recommend everyone switch on a personal computer:
nlm auth storage set protected
๐ก You can also use the 'nlm setup' wizard and select the 'Credentials Protection' option in the wizard
Optional: nothing changes unless you turn it on. Servers, cron, Docker and SSH setups can keep the plain file.
๐ How it works ยท ๐บ
Key features
01. โ Install, login, agent setup, and migration from another Gemini Notebook MCP
02. โ Complete command reference
03. โ All 53 MCP tools with examples
04. โ Setup and troubleshooting
05. โ Web/mobile connector feasibility, security, and authentication limitations
๐ค Fun fact: this video was created by an agent using the gemini-notebook-mcp.
Note: Personal/consumer accounts are tested regularly. Gemini Notebook Enterprise support is experimental. The documented notebook.cloud.google.com host has been live-verified with a project-qualified global deployment; other Enterprise host variants may require additional validation.
โ If you find notebooklm-mcp-cli useful, consider buying me a coffee.
It's free and built in my spare time โ but testing every Gemini Notebook feature takes real time and resources. A coffee helps me cover it and keep shipping. Thank you! ๐
๐บ Watch the Demos
Latest
Claude Cowork & Interactive Reports
Codex Setup + Cinematic Video & Slides
MCP Demos
General Overview
Claude Desktop
Perplexity Desktop
MCP Super Assistant
CLI Demos
CLI Overview
CLI, MCP & Skills
Setup, Doctor & mcpb
Infographics Support
โก Quick Start
Three commands take you from nothing to a connected AI assistant:
Install (gives you nlm and the MCP server):
uv tool install notebooklm-mcp-cli
Sign in to your Google account:
nlm login
Connect your AI tools:
nlm setup
The setup wizard (nlm setup)
nlm setup finds the AI tools installed on your machine and connects them to
Gemini Notebook โ no config files to edit. Pick an option with the arrow keys:
Menu option
What it does
Show my tools' status
One table for every detected tool: MCP connection (โ set up ยท โ not yet ยท โ old name) and skill version (โฌ when an upgrade is available).
Add the MCP to my tools/agents
Tick the tools to connect (Space), then Enter. Nothing is pre-selected. Connections still using the old notebooklm-mcp name appear under Needs a fix and are renamed to gemini-notebook-mcp, keeping their settings. Then it offers the skill.
Add the skill to my tools/agents
Installs the skill that teaches your AI how to use Gemini Notebook well โ for All my projects (default) or Just this folder. Upgrades are pre-ticked; older versions are only replaced after you confirm.
Remove an MCP or skill
Lists what's installed, grouped into MCP connections and skills. Nothing is pre-selected, and each group needs its own confirmation.
Credential protection
Protect your saved logins in your OS keystore, or restore them to plain files. It only offers what applies: Protect when a login is plain, Restore when one is protected. With several logins you get a checkbox picker.
Copy MCP setup for a tool not listed
Copies a ready-to-paste JSON snippet to your clipboard. Advanced options switch to uvx, the bare command, or entry-only JSON.
Esc goes back from any screen (and quits from the main menu).
Every file is backed up to ~/.notebooklm-mcp-cli/backups/ before it is changed.
Connects to: Claude Code, Claude Desktop (regular and Relay AI / 3P), Codex CLI / ChatGPT desktop app, Gemini CLI, Cursor, Windsurf, Cline, Antigravity, GitHub Copilot (VS Code), and OpenCode. The skill also installs for Hermes and OpenClaw.
Claude Desktop Chat & Cowork, and claude.ai: these only use skills uploaded to your Claude account. In Add the skill, tick Claude Desktop / claude.ai โ the wizard saves ~/Downloads/nlm-skill.zip and shows where to upload it (Customize โ Skills โ Add). Or run nlm skill package.
Claude Desktop: fully quit it (Cmd+Q) before connecting โ it can overwrite its settings while open, so the wizard refuses to write until it's closed.
Scripts and CI: every option has a direct command โ nlm setup add <tool>, nlm setup remove <tool>, nlm setup list, nlm skill install <tool>. See MCP Configuration.
Two Ways to Use
๐ฅ๏ธ Command-Line Interface (CLI)
Use nlm directly in your terminal for scripting, automation, or interactive use:
nlm notebook list # List all notebooks
nlm notebook create "Research Project" # Create a notebook
nlm source add <notebook> --url "https://..." # Add sources
nlm audio create <notebook> --confirm # Generate podcast
nlm download audio <notebook> --id <artifact-id> # Download audio file
nlm download all <notebook> -d ./exports # Download every artifact
nlm share public <notebook> # Enable public link
Run nlm --ai for comprehensive AI-assistant documentation.
๐ค MCP Server (for AI Agents)
Connect AI assistants (Claude, Gemini, Cursor, etc.) to Gemini Notebook:
nlm setup # Guided wizard โ see Quick Start above
nlm setup add codex # Or connect one client directly
Then use natural language: "Create a notebook about quantum computing and generate a podcast"
Features
Capability
CLI Command
MCP Tool
List notebooks
nlm notebook list
notebook_list
Create notebook
nlm notebook create
notebook_create
Add Sources (URL, Text, Drive, File)
nlm source add
source_add
Query notebook (persists to web UI)
nlm notebook query
notebook_query
List/view/export chat sessions
nlm chats list/get/export
chat_list/chat_get/chat_export
Create Studio Content (Audio, Video, etc.)
nlm studio create
studio_create
Interactive reports (read + embedded elements)
nlm report get/elements/element
report (action=get/elements/generate)
Revise slide decks
nlm slides revise
studio_revise
Download artifacts
nlm download <type>
download_artifact
Download all artifacts (one or all notebooks)
nlm download all
download_all_artifacts
Web/Drive research
nlm research start
research_start
Share notebook
nlm share public/invite
notebook_share_*
Sync Drive sources
nlm source sync
source_sync_drive
Batch operations
nlm batch query/create/delete
batch
Cross-notebook query
nlm cross query
cross_notebook_query
Pipelines (multi-step workflows)
nlm pipeline run/list
pipeline
Tag & smart select
nlm tag add/list/select
tag
Manage collections (home page groups)
โ
collection_*
Configure AI tools
nlm setup (wizard), nlm setup add/remove/list
โ
Install AI Skills
nlm skill install/update
โ
Diagnose issues
nlm doctor
โ
Check remaining plan usage
nlm usage [--profile <name>]
usage_get
Manage login encryption (Protected mode)
nlm auth storage status/set
โ
๐ More Documentation:
Getting Started โ Install, login, agent setup, and migration from another Gemini Notebook MCP
After removing legacy packages, reinstall to fix symlinks:
uv tool install --force notebooklm-mcp-cli
Why --force? When multiple packages provide the same executable, uv can leave broken symlinks after uninstalling. The --force flag ensures clean symlinks.
Step 4: Verify Installation
uv tool list | grep notebooklm
You should see only:
notebooklm-mcp-cli v0.2.0
- nlm
- notebooklm-mcp
Step 5: Re-authenticate
Your existing cookies should still work, but if you encounter auth issues:
nlm login
Note: The configured MCP server name is now gemini-notebook-mcp. The executable remains notebooklm-mcp for compatibility with existing installations.
Getting Started
If you are setting up the tool for the first time โ or migrating from a
browser-based Gemini Notebook MCP โ see the
Getting Started Guide. It covers install,
login, agent registration, and a step-by-step migration path that avoids
the "two Gemini Notebook servers registered" trap.
Uninstalling
To completely remove the MCP:
# Using uv
uv tool uninstall notebooklm-mcp-cli
# Using pip
pip uninstall notebooklm-mcp-cli
# Using pipx
pipx uninstall notebooklm-mcp-cli
# Remove cached auth tokens and data (optional)
rm -rf ~/.notebooklm-mcp-cli
Also remove from your AI tools:
nlm setup remove claude-code
nlm setup remove cursor
# ... or any configured tool
Authentication
Before using the CLI or MCP, you need to authenticate with Gemini Notebook:
CLI Authentication (Recommended)
# Auto mode: launches your browser, you log in, cookies extracted automatically
nlm login
# Check if already authenticated
nlm login --check
# Use a named profile (for multiple Google accounts)
nlm login --profile work
nlm login --profile personal
# Manual mode: import cookies from a file
nlm login --manual --file cookies.txt
# External CDP provider (e.g., OpenClaw-managed browser)
nlm login --provider openclaw --cdp-url http://127.0.0.1:18800
New profiles ask where to keep the saved login before the browser opens: Protected (encrypted, key in your OS keystore, recommended) or a plain file. Scripts can skip the question with nlm login --storage protected (or --storage file). Existing profiles keep their mode; change it any time in nlm setup โ Credential protection.
Profile management:
nlm login --check # Show current auth status
nlm login switch <profile> # Switch the default profile
nlm login profile list # List all profiles with email addresses
nlm login profile delete <profile> # Delete a profile
nlm login profile rename <old> <new> # Rename a profile
From an MCP-only app (for example Claude CoWork): ask the AI to use the profile tool. It can list your accounts, switch for the session, and, only if you ask, make one your saved default.
Unattended / scheduled refresh:
A live session self-heals โ when Google's short-lived cookies age out, the
client automatically runs a headless refresh. For unattended machines you can
also refresh proactively from a scheduler so a session never lapses:
nlm auth refresh # Headless, no interaction; exits non-zero on failure
nlm auth refresh --profile work # Refresh a named profile
nlm auth refresh --http-only # Validate without opening a browser
--http-only forces HTTP transport, including when CDP transport is configured.
It cannot renew browser-dependent PSIDTS cookies or revive a fully expired login.
Automatic recovery uses a per-process cooldown and failure budget; explicit
refresh commands bypass these limits. See authentication guidance.
Run browser-based refresh on a timer (cron/launchd). It needs a saved Chrome profile from a prior
nlm login, and does not apply when NOTEBOOKLM_COOKIES is set as an
environment variable (that value overrides saved credentials).
For organizations using Gemini Notebook Enterprise via Google Cloud, ask your Enterprise administrator for the project ID or number, the deployment location/multi-region, and confirmation that your account has access. The current documented host is notebook.cloud.google.com; older deployments may use notebooklm.cloud.google.com or vertexaisearch.cloud.google.com.
Set Base URL, GCP Project ID & Location:
export NOTEBOOKLM_BASE_URL="https://notebook.cloud.google.com"
# Required: your GCP project ID or project number from your administrator
export NOTEBOOKLM_PROJECT_ID="your-gcp-project-id-or-number"
# Optional: GCP location/multi-region from your administrator: global (default), us, or eu
export NOTEBOOKLM_LOCATION="global"
Save an Enterprise Auth Profile:
This opens the configured Enterprise URL in an isolated browser profile. Sign in with your organization account:
You can switch back to a personal profile at any time:
unset NOTEBOOKLM_BASE_URL NOTEBOOKLM_PROJECT_ID NOTEBOOKLM_LOCATION
nlm login switch personal
Configure MCP Server with Enterprise Environment Variables:
When adding the MCP server to AI assistants (Claude, Cursor, etc.), pass NOTEBOOKLM_BASE_URL, NOTEBOOKLM_PROJECT_ID, and optionally NOTEBOOKLM_LOCATION:
Each profile gets its own isolated browser session, so you can be logged into multiple Google accounts simultaneously. Enterprise environment variables apply to the current process, so keep them in an Enterprise-only shell or MCP configuration when you also use a personal account.
How it works: Auto mode launches a dedicated browser profile (supports Chrome, Arc, Dia, Comet, Brave, Edge, Chromium, Firefox, and more), you log in to Google, and cookies are extracted automatically. Your login persists for future auth refreshes.
Prefer a specific browser? Set it with nlm config set auth.browser chromium (or comet, dia, brave, arc, edge, chrome, firefox, etc.). Falls back to auto-detection if the preferred named browser is not found. For any other Chromium-compatible browser, set its executable with nlm config set auth.browser_path /path/to/browser or NLM_BROWSER_PATH; an invalid explicit path fails closed instead of launching a different browser. When Chromium/CDP is unavailable, auto can fall back to Firefox.
โ ๏ธ Context Window Warning: This MCP provides 53 tools. Disable it when not using Gemini Notebook to preserve context. In Claude Code: @gemini-notebook-mcp to toggle. To keep it on but expose only a subset, see Selective tool exposure.
Automatic Setup (Recommended)
The setup wizard is the recommended way to connect tools โ see
Quick Start for what each menu option does:
nlm setup
MCP configuration goes to each app's user-level settings. Codex CLI and the
ChatGPT desktop app share one MCP configuration on the same host. GitHub
Copilot uses the VS Code user profile in the wizard; the direct command without
--scope user targets the current workspace.
For direct setup or scripts, keep using the existing commands:
nlm setup add codex # Codex CLI / ChatGPT desktop
nlm setup add github-copilot --scope user # VS Code user profile
nlm setup add github-copilot # Current workspace
nlm setup add claude-desktop --profile 3p # Relay AI / Claude 3P
nlm setup list # Show MCP configuration status
Claude Desktop setup only writes to profiles that are detected as present. If
both regular and Relay AI/3P profiles exist, the CLI asks whether to configure
regular, 3P, or both. For scripts, use --profile regular|3p|both. If no
Claude Desktop profile is detected, nothing is created or changed.
Removal uses the same profile selection, for example
nlm setup remove claude-desktop --profile regular.
Removal only offers detected profiles containing this MCP or a recognized
legacy entry; unrelated MCP servers are left untouched.
Before adding or removing the MCP, fully quit the selected Claude Desktop
profile. The CLI detects running regular and Relay AI/3P instances and refuses
to write while they are open, because Claude may rewrite the config and discard
the change. Reopen Claude Desktop after setup completes.
Install AI Skills (Optional)
The wizard can install the prompting and workflow skill after MCP setup. It
defaults to All projects (user level) and can instead install into the
current project. Existing current or newer versions are preserved; older or
unversioned skills require confirmation before replacement, with a backup made
first.
You can also manage skills directly. Supported local skill targets include
Cline, Antigravity, OpenClaw, Hermes, Codex, OpenCode,
Claude Code, and Gemini CLI.
User-level skill installation requires the target tool to be detected first;
the CLI will not create a missing tool directory or install anyway. Use
--level project when you intentionally want a project-local skill.
Claude Desktop (Chat and Cowork) and claude.ai
Claude Desktop's Code tab is Claude Code, so it uses the skill installed in
~/.claude/skills/. The Chat and Cowork tabs, and claude.ai, only use
skills uploaded to your Claude account. Create the upload file with the wizard
(tick Claude Desktop / claude.ai in Add the skill) or directly:
Then in Claude Desktop (or claude.ai) open Customize โ Skills โ Add, pick
nlm-skill.zip, and turn the skill on. Re-upload after updating nlm to get
the latest skill. The MCP for Chat and Cowork comes from the normal Claude
Desktop connection (nlm setup โ Add the MCP).
Remove from a tool
nlm setup remove claude-code
Using uvx (No Install Required)
If you don't want to install the package, you can use uvx to run on-the-fly:
๐ Full configuration details:MCP Guide โ Server options, environment variables, HTTP transport, and context window management. For Claude web/mobile and public deployment, read Remote MCP Deployment first.
What You Can Do
Simply chat with your AI tool (Claude Code, Cursor, Gemini CLI) using natural language. Here are some examples:
Research & Discovery
"List all my Gemini Notebook notebooks"
"Create a new notebook called 'AI Strategy Research'"
"Start web research on 'enterprise AI ROI metrics' and show me what sources it finds"
"Do a deep research on 'cloud marketplace trends' and import the top 10 sources"
"Search my Google Drive for documents about 'product roadmap' and create a notebook"
Pro tip: After creating studio content (audio, video, reports, etc.), poll the status to get download URLs when generation completes.
Authentication Lifecycle
Component
Duration
Refresh
Cookies
~2-4 weeks
Auto-refresh via headless browser (if profile saved)
CSRF Token
~minutes
Auto-refreshed on every request failure
Session ID
Per MCP session
Auto-extracted on MCP start
v0.1.9+: The server now automatically handles token expiration:
Refreshes CSRF tokens immediately when expired
Reloads cookies from disk if updated externally
Runs headless browser auth if profile has saved login
You can also call refresh_auth() to explicitly reload and validate tokens, or
refresh_auth(profile="work") to refresh a named saved account without
switching the MCP server's active account.
If automatic refresh fails (Google login fully expired), run nlm login again.
For suspected browser-bound auth replay failures, run nlm doctor auth-replay.
If the cdp_in_page probe succeeds while normal replay fails, see
Experimental browser-backed RPC transport.
Troubleshooting
uv tool upgrade Not Installing Latest Version
Symptoms:
Running uv tool upgrade notebooklm-mcp-cli installs an older version (e.g., 0.1.5 instead of 0.1.9)
uv cache clean doesn't fix the issue
Why this happens:uv tool upgrade respects version constraints from your original installation. If you initially installed an older version or with a constraint, upgrade stays within those bounds by design.
Fix โ Force reinstall:
uv tool install --force notebooklm-mcp-cli
This bypasses any cached constraints and installs the absolute latest version from PyPI.
Verify:
uv tool list | grep notebooklm
# Should show: notebooklm-mcp-cli v0.1.9 (or latest)
Limitations
Rate limits: Chat and Studio usage is metered as compute against a rolling (~5h) window and a weekly cap, scaled by plan tier. Run nlm usage to see what is left and when it resets
No official support: API may change without notice
Cookie expiration: Need to re-extract cookies every few weeks
Contributing
See CLAUDE.md for detailed API documentation and how to add new features.
Vibe Coding Alert
Full transparency: this project was built by a non-developer using AI coding assistants. If you're an experienced Python developer, you might look at this codebase and wince. That's okay.
The goal here was to scratch an itch - programmatic access to Gemini Notebook - and learn along the way. The code works, but it's likely missing patterns, optimizations, or elegance that only years of experience can provide.
This is where you come in. If you see something that makes you cringe, please consider contributing rather than just closing the tab. This is open source specifically because human expertise is irreplaceable. Whether it's refactoring, better error handling, type hints, or architectural guidance - PRs and issues are welcome.
Think of it as a chance to mentor an AI-assisted developer through code review. We all benefit when experienced developers share their knowledge.
Credits
Special thanks to:
Le Anh Tuan (@latuannetnam) for contributing the HTTP transport, debug logging system, and performance optimizations.
David Szabo-Pele (@davidszp) for the source_get_content tool and Linux auth fixes.
saitrogen (@saitrogen) for the research polling query fallback fix.
devnull03 (@devnull03) for multi-browser CDP authentication support (Arc, Brave, Edge, Chromium, Vivaldi, Opera).
VooDisss (@VooDisss) for multi-browser authentication improvements.
codepiano (@codepiano) for the configurable DevTools timeout for the auth CLI.
Tony Hansmann (@997unix) for contributing the nlm setup and nlm doctor commands and CLI Guide documentation.
Fabiana Furtado (@fabianafurtadoff) for batch operations, cross-notebook query, pipelines, and smart select/tagging (PR #90).
Amy-Ra-lph (@Amy-Ra-lph) for security hardening: TOCTOU-safe credential storage, sensitive cookie redaction from debug logs, and pinning all CI actions to full commit SHAs (PRs #205โ207).
Kyle Brodeur (@kylebrodeur) for WSL2 authentication support with Windows Chrome integration (PR #138).
Robiton (@Robiton) for enterprise Gemini Notebook support via configurable base URL (PR #114).
pjeby (@pjeby) for connection pooling and fast startup improvements (PR #54).
beausea (@beausea) for making the interface language configurable via the NOTEBOOKLM_HL environment variable (PR #59).
JumpLao (@JumpLao) for extended audio, video, and image format support (PR #82).
cbruyndoncx (@cbruyndoncx) for including cited_text passages in query output (PR #81).
zxyasfas (@zxyasfas) for cited-only research import (PR #188).
Serdar Akฤฑn (@SERDAR-AKIN) for the multi-probe AuthHealthChecker that fixes false "stale" reports for semi-stale cookies (PR #219).
