Notebooklm MCP

NotebookLM (Gemini Notebook) — CLI + MCP

Google NotebookLM has no official API. The notebooklm-mcp-cli package (nlm CLI + notebooklm-mcp server) is a third-party, unofficial client that authenticates by extracting browser cookies from a logged-in Google session and caching them. This skill covers the two headless-friendly auth methods and the MCP server wiring.

Security note: a cookies.txt file or the cached auth.json is equivalent to a Google session. The agent must never extract, read, or forward cookie values without the user's explicit consent.

Both paths share the same cookie cache at ~/.notebooklm-mcp-cli/profiles/<profile>/auth.json.

When to use

• devin mcp list / claude mcp list shows notebooklm-mcp failing to list tools.
• nlm login --check fails with ClientAuthenticationError or network_error.
• nlm doctor reports "Browser: not found" (headless server).
• The user wants to authenticate NotebookLM on a server without a desktop browser.
• The user asks to configure the NotebookLM MCP server for Claude Code / Cursor / Devin / Gemini.
• You need to extract Google cookies manually or via an external CDP endpoint.

When NOT to use

• The user wants a generic "scrape Google docs" tool — NotebookLM is specifically for the NotebookLM product.
• The user is on a desktop with Chrome installed — just run nlm login (auto mode); no skill needed.

Guardrails

• Pin the CLI version: install notebooklm-mcp-cli with an explicit ==<VERSION>; do not run bare uv tool install or pipx install without a version.
• Verify upstream before install: confirm the package name and version on PyPI and the upstream source. Treat it as an unofficial client.
• Human confirmation required: the agent must ask the user before extracting or importing cookies. Do not automate cookie collection from a browser the user does not control.
• Cookies are credentials: a cookies.txt file or the cached auth.json is equivalent to a Google session. Never commit, share, log, or screenshot them. Delete cookies.txt immediately after nlm login --manual --file succeeds.
• No credential brokering: run nlm login as a black-box command. Do not read, parse, or transmit the contents of cookies.txt or auth.json.
• Prefer official auth: use desktop nlm login auto mode when a browser is available. Use manual cookie mode only on headless servers the user controls.
• No browser data harvesting: extract cookies only from the user's own browser session; do not use extracted cookies for any purpose other than authenticating nlm.
• Verify before trusting: run nlm login --check and nlm doctor before any notebook operation.

Install

Pin a known version before installing. Replace <VERSION> with the latest stable from pip index versions notebooklm-mcp-cli or the version required by the project.

# Option 1: uv (recommended)
uv tool install notebooklm-mcp-cli==<VERSION>

# Option 2: pipx
pipx install notebooklm-mcp-cli==<VERSION>

# Option 3: pip (only in a virtual environment; avoid --user)
pip install notebooklm-mcp-cli==<VERSION>

Verify:

nlm --version          # 0.9.x
which nlm notebooklm-mcp

Run the diagnostic at any time:

nlm doctor             # checks install, auth, browser, AI-tool configs
nlm doctor -v          # verbose

Authentication

NotebookLM auth = Google browser cookies. There is no API key. Three methods work on headless servers:

Fallback order on headless boxes: try OpenClaw CDP first (if a managed browser is running on port 18800) → fall back to manual cookie file → fall back to running nlm login on a desktop with a browser and copying the resulting auth.json.

OpenClaw CDP (preferred for OpenClaw users)

OpenClaw runs a managed browser with Chrome DevTools Protocol (CDP) on port 18800 by default. nlm can read cookies from this browser session without launching a second browser:

nlm login --provider openclaw --cdp-url http://127.0.0.1:18800

If you configured a custom OpenClaw browser profile with a different CDP port:

# Check your OpenClaw browser config
openclaw config get browser.profiles

# Use the matching CDP port
nlm login --provider openclaw --cdp-url http://127.0.0.1:<port>

The OpenClaw browser must already be logged in to Google / NotebookLM. Uses suppress_origin=True for websocket CDP commands to support managed endpoints that reject the default Origin header.

Method 1 — Manual cookie file

Step 1: Extract cookies on a machine with Chrome

1. Open Chrome and go to https://notebooklm.google.com
2. Make sure you are logged in to your Google account.
3. Press F12 (or Cmd+Option+I on Mac) to open DevTools.
4. Click the Network tab.
5. In the filter box, type: batchexecute
6. Click on any notebook to trigger a request.
7. Click on a batchexecute request in the list.
8. In the right panel, scroll to Request Headers.
9. Find the line starting with cookie:.
10. Right-click the cookie value and select Copy value.
11. Paste into a text file and save as cookies.txt.

Cookie file format

The file should contain the raw cookie string from Chrome DevTools:

SID=abc123...; HSID=xyz789...; SSID=...; APISID=...; SAPISID=...; __Secure-1PSID=...; __Secure-3PSID=...; ...

• Lines starting with # are treated as comments and ignored.
• The file can contain the cookie string on one or multiple lines.
• A template cookies.txt is included in the repository.

Step 2: Import on the server

# Copy cookies.txt to the server, then:
nlm login --manual --file cookies.txt

# Or interactive mode (prompts for the file path):
nlm login --manual

Step 3: Verify

nlm login --check
# ✓ Authenticated as user@example.com

nlm doctor
# Authentication: cookies present, CSRF token: yes, account: user@example.com

Tokens are cached at ~/.notebooklm-mcp-cli/profiles/default/auth.json.

Method 2 — OpenClaw CDP provider

If an OpenClaw-managed browser is already running and exposing a Chrome DevTools Protocol endpoint, nlm can read cookies from it without launching a second browser:

nlm login --provider openclaw --cdp-url http://127.0.0.1:18800

• Uses suppress_origin=True for websocket CDP commands to support managed endpoints that reject the default Origin header.
• The browser must already be logged in to Google / NotebookLM.
• Increase the DevTools timeout if the endpoint is slow: nlm login --provider openclaw --cdp-url http://127.0.0.1:18800 --devtools-timeout 15

Verify the same way:

nlm login --check

Method 3 — Auto mode (desktop with browser)

On a desktop with Chrome/Chromium/Brave/Edge/Arc/Firefox installed:

nlm login              # launches a dedicated browser profile, you log in, cookies extracted

Prefer a specific browser:

nlm config set auth.browser chromium   # or brave, arc, edge, chrome, firefox, vivaldi, opera

Multi-profile auth

Multiple Google accounts are supported via named profiles:

nlm login --profile work
nlm login --profile personal
nlm login switch work
nlm login profile list
nlm login profile delete personal

The MCP server always uses the active default profile. Switching the default profile instantaneously switches the MCP server's Google account:

nlm login switch personal
nlm config set auth.default_profile personal

Auth lifecycle

When cookies go stale:

nlm login --check        # reports stale/unverified
nlm login                # re-extract (auto mode)
nlm login --manual --file cookies.txt   # re-extract (manual mode)

PATH A — CLI usage

# Notebooks
nlm notebook list
nlm notebook create --title "My Notebook"
nlm notebook get <notebook_id>
nlm notebook delete <notebook_id>

# Sources
nlm source add <notebook_id> --url https://example.com/doc
nlm source add <notebook_id> --file ./paper.pdf
nlm source list <notebook_id>

# Notes
nlm note add <notebook_id> --text "My note"
nlm note list <notebook_id>

# Chat
nlm chats start <notebook_id>
nlm chats send <notebook_id> "Summarize the sources"

# Audio overviews
nlm audio create <notebook_id>
nlm download <notebook_id> --artifact audio

# Reports
nlm report create <notebook_id> --topic "Key findings"

# Research
nlm research discover "climate adaptation strategies"

# Batch + cross-notebook
nlm batch <notebook_ids_file> --command "summarize"
nlm cross query "find mentions of X across all notebooks"

# Tags + labels
nlm tag add <notebook_id> research
nlm label add <notebook_id> source_1 priority

# Sharing + export
nlm share <notebook_id> --email collaborator@example.com
nlm export <notebook_id> --format docs

# Diagnostics
nlm doctor
nlm doctor auth-replay     # diagnose cookie replay vs browser-bound auth failures

PATH B — MCP server

B.1 Configure

The easiest way is nlm setup (covers Claude Code, Claude Desktop, Cursor, Gemini CLI, GitHub Copilot, Windsurf):

nlm setup add claude-code       # Claude Code
nlm setup add claude-desktop    # Claude Desktop
nlm setup add gemini            # Gemini CLI / Antigravity IDE
nlm setup add github-copilot    # GitHub Copilot
nlm setup add cursor            # Cursor
nlm setup add windsurf          # Windsurf
nlm setup add json              # Any other tool (interactive JSON generator)

nlm setup list                  # show supported tools + their MCP config status

For platforms not covered by nlm setup (Devin CLI/Desktop, OpenCode, Antigravity CLI, OpenClaw), use the bundled setup script or edit the config manually.

Per-platform config — critical gotchas

Each MCP client platform has its own config format. Getting field names wrong causes the server to be silently ignored (no error, just no tools). See references/platform-quirks.md for the full matrix.

Top 3 silent-failure traps:

1. OpenCode uses mcp (not mcpServers), environment (not env), command as single array (binary + args merged).
2. OpenClaw uses mcp.servers (dotted) with transport: "stdio", managed via openclaw mcp add/set.
3. Antigravity caches MCP servers in ~/.gemini/antigravity{,-ide,-cli}/mcp/ — must delete cache dir to uninstall.

See references/mcp-config.md for the exact JSON block per platform.

Automated setup helper

Run the bundled helper to detect all installed platforms and patch each with the correct format:

bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh
# dry-run:
bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh --dry-run
# target one platform:
bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh --platform cursor
# use bare notebooklm-mcp binary instead of nlm wrapper:
bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh --binary notebooklm-mcp
# remove:
bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh --remove

Transport options

notebooklm-mcp                          # stdio (default, for local agents)
notebooklm-mcp --transport http --port 8000   # HTTP (for remote agents)
notebooklm-mcp --transport sse  --port 8000   # SSE

Env vars:

Remote MCP warning: HTTP transport does not provide HTTPS, caller authentication, per-user NotebookLM accounts, or remote file transfer. Do not expose it publicly without a reverse proxy adding TLS + auth.

B.2 Verify

After configuring, restart the agent. The MCP server exposes ~30 tools. Check from the agent:

mcp_list_tools("notebooklm-mcp")
# Expect: notebook_create, notebook_list, source_add, source_list, chat_send,
#         audio_create, report_create, refresh_auth, save_auth_tokens, ...

From the shell:

bash skills/notebooklm-mcp/scripts/verify_notebooklm.sh

B.3 Auth tools exposed via MCP

If MCP tool calls fail with auth errors, call refresh_auth first. If that fails, re-run nlm login on the host.

Headless auth flow (decision diagram)

┌────────────────────────────────────────────────────────────────┐
│ Is an OpenClaw browser running with CDP on 127.0.0.1:18800?    │
│   YES → nlm login --provider openclaw --cdp-url http://...     │
│   NO  ↓                                                        │
│ Do you have a cookies.txt file (extracted on another machine)? │
│   YES → nlm login --manual --file cookies.txt                  │
│   NO  ↓                                                        │
│ Can you run nlm login on a desktop with Chrome?                │
│   YES → nlm login (auto mode) → copy auth.json to the server   │
│         (cp ~/.notebooklm-mcp-cli/profiles/default/auth.json   │
│            server:~/.notebooklm-mcp-cli/profiles/default/)     │
│   NO  → cannot authenticate; NotebookLM needs Google cookies   │
└────────────────────────────────────────────────────────────────┘

Troubleshooting

References

• references/mcp-config.md — Full per-platform JSON config blocks (Claude Code/Desktop, Cursor, Devin CLI/Desktop, OpenCode, Antigravity IDE/CLI, OpenClaw).
• references/platform-quirks.md — Cross-platform MCP config quirks matrix (serverUrl vs url, mcp vs mcpServers, environment vs env, env substitution syntax, OpenClaw CDP ports).
• references/auth-guide.md — Deep dive on cookie extraction, file format, multi-profile, OpenClaw CDP, and auth lifecycle.
• scripts/setup_notebooklm_mcp.sh — Detects all installed platforms and patches each with the correct format (handles mcp/mcpServers, command array, environment/env, OpenClaw CLI).
• scripts/verify_notebooklm.sh — Runs nlm doctor + nlm login --check + lists notebooks to confirm end-to-end.
• scripts/extract_cookies_help.sh — Prints the step-by-step cookie extraction instructions for the user.
• Authentication guide (upstream)
• MCP guide (upstream)
• CLI guide (upstream)
• PyPI
• Devin CLI MCP configuration
• Antigravity MCP docs
• OpenCode MCP servers
• OpenClaw MCP tools
• OpenClaw browser CDP
• Cursor MCP docs