NotebookLM MCP CLI

What It Does

NotebookLM MCP CLI is a unified Python package that gives AI agents, developers, and power users programmatic access to Google NotebookLM (notebooklm.google.com). Google publishes no official API for NotebookLM, so this project reverse-engineers the internal batchexecute RPCs that the web frontend itself uses. It ships three interfaces in one install: a 39-tool MCP server (notebooklm-mcp) for AI assistants like Claude Code, Cursor, and Gemini CLI; a 22-command CLI (nlm) for terminal scripting; and a native agent skill (SKILL.md plus six reference files) installable for Hermes, Claude Code, Cursor, Codex, OpenCode, Antigravity, and generic agents formats. The tool covers the full NotebookLM surface: notebook CRUD, source management (URLs, YouTube, text, Google Drive, file uploads), Studio content generation (podcasts, video, reports, quizzes, flashcards, mind maps, slides, infographics, data tables), web and Drive research, cross-notebook queries, batch operations, multi-step pipelines, sharing, and artifact downloads.

The Good

The MCP server is fast, spec-compliant, and thoroughly tooled. The initialize handshake completes in 0.5 seconds and returns a properly structured serverInfo object with capabilities for tools, prompts, resources, logging, and extensions. The tools/list response enumerates all 39 tools, each with a complete JSON Schema input definition (properties, types, required fields, additionalProperties: false). Ten tools that perform destructive or expensive operations carry a confirm boolean parameter (batch, notebook_delete, note, notebook_share_batch, source_sync_drive, source_delete, studio_create, studio_delete, studio_revise, label), enforcing a human approval gate that the SKILL.md instructs agents to respect. The tool grouping system (tool_groups.py) lets clients hide entire tool categories via the NOTEBOOKLM_DISABLED_GROUPS environment variable, which directly addresses the context window pressure that 39 tools create.

The test suite is large, green, and fast. The project ships 78 test files totaling 16,111 lines. Running pytest produces 1120 passed and 39 skipped in 24 seconds. The skipped tests are marked @pytest.mark.e2e and require live Google authentication, which is the correct call for CI. Test coverage spans the core client layer, CDP transport, cookie rotation, conversation management, downloads, notebook CRUD, source reconciliation, research polling, studio operations, sharing, and every CLI command group (login, studio, source, repl, formatters, verbs parity). The ratio of test code to production code is approximately 1:3 (16K test lines vs 50K source lines), which is healthy for a project of this scope.

The agent skill is real, not a stub. The bundled SKILL.md is 891 lines of structured guidance with YAML frontmatter (name, version, description with trigger keywords). It ships six reference files: studio-prompting-guide.md, studio-prompt-examples.md, command_reference.md, troubleshooting.md, workflows.md, and remote-mcp.md. The skill documents both the MCP tool path and the CLI path, includes a workflow decision tree, lists 13 critical rules (including "always ask user before delete"), and provides quick-format-pick tables for Studio content generation. Running nlm skill install hermes writes the skill to .hermes/skills/nlm-skill/ with all seven files. The same command works for claude-code, cursor, codex, opencode, antigravity, agents, and other.

Setup automation is extensive and well-designed. The nlm setup add command auto-configures the MCP server for six AI tools (Claude Code, Claude Desktop, Gemini, GitHub Copilot, Cursor, Windsurf) by writing the correct JSON config to each tool's expected location. The nlm doctor command runs a diagnostic that checks the installation path, authentication status, browser availability, and AI tool configurations, then prints actionable suggestions. The nlm --ai flag generates a thorough AI-optimized command reference that an agent can read directly. The Claude Desktop .mcpb extension (build via scripts/build_mcpb.py) enables one-click install from the GitHub releases page.

The development cadence and contributor base are strong for a solo-origin project. The CHANGELOG documents 127 tagged versions, with the latest (0.8.7) shipped the day before this review. Fourteen contributors are credited by name with specific PRs, including security hardening (TOCTOU-safe credential storage, cookie redaction from debug logs, CI action SHA pinning), WSL2 auth support, enterprise NotebookLM base URL configuration, connection pooling, multi-browser CDP auth (Arc, Brave, Edge, Chromium, Vivaldi, Opera), and batch operations. Four CI workflows run lint-test, publish, release-gate, and version-check. The PyPI package has 112 published releases.

The Bad

The entire architecture depends on undocumented Google internal APIs and browser cookie extraction. The README states plainly: "This MCP and CLI use internal APIs that are undocumented and may change without notice" and "require cookie extraction from your browser." Authentication works by launching a Chromium-family browser, having the user log in to Google, then extracting cookies via Chrome DevTools Protocol. These cookies expire after 2 to 4 weeks, requiring re-authentication. The free tier has approximately 50 queries per day. Any change Google makes to the NotebookLM web frontend can break the RPC layer overnight, and the KNOWN_ISSUES.md documents this fragility honestly (the bl build label parameter, cookie expiration cycles, CSRF token refresh). This is the fundamental structural limitation: there is no fix until Google publishes an official API.

The serverInfo version field reports the FastMCP SDK version (3.4.4), not the package version (0.8.7). This is a variant of the version-drift pattern seen in other FastMCP-based servers (awslabs/mcp, PrefectHQ/fastmcp). An MCP client or registry that reads serverInfo.version for compatibility checks or update prompts will see "3.4.4" and have no way to know the actual package is 0.8.7. The server_info tool and nlm --version both report the correct 0.8.7, but the MCP protocol-level serverInfo field is misleading.

The README has a stale tool count reference. The documentation links section says "MCP Guide - All 35 MCP tools with examples," but the actual tool count is 39 (confirmed by tools/list). The MCP_GUIDE.md header was likely written when the tool set was smaller and has not been updated to reflect the current 39-tool surface. The MCP_GUIDE.md itself may have the correct count, but the README link text is wrong.

The project requires Python 3.11 or newer. Many Linux distributions and macOS ship Python 3.9 or 3.10 as the system default. Users without uv or pyenv will hit a version error on pip install. The pyproject.toml specifies requires-python = ">=3.11" and classifiers list 3.11, 3.12, and 3.13. The uv-based install path handles this automatically, but pip-only users may be surprised.

Authentication cannot be automated in a headless or CI environment without a saved browser profile. The nlm login command launches a visible browser window for the initial authentication. Subsequent refreshes can use headless mode if a profile was saved, but the first login requires a desktop browser. This rules out fully automated deployment on servers without a display unless you use the manual cookie import path (nlm login --manual --file cookies.txt), which requires extracting cookies through other means first.

Smoke Test Results

Tested on macOS (host) with uv tool install notebooklm-mcp-cli. Python 3.12.13 via uv-managed environment. No Google credentials available, so all functional tests are limited to the server protocol layer, CLI commands, and skill installation.

Run A - Fresh install, no deps preinstalled

$ uv tool install notebooklm-mcp-cli
Installed 2 executables: nlm, notebooklm-mcp
✅ Clean install, 81 packages resolved

$ nlm --version
nlm version 0.8.7
✅ Version correct

$ nlm --help
[22 command groups listed: login, notebook, label, note, source, chat,
 studio, research, alias, config, download, share, export, skill, setup,
 doctor, batch, cross, pipeline, tag, audio, report, quiz, ...]
✅ CLI responsive

Pass rate: 3 of 3. The install is a single command and produces both executables immediately.

Run B - MCP server protocol verification

$ python3 mcp-client.py notebooklm-mcp --transport stdio --read-only
=== INITIALIZE ===
serverInfo: {"name": "notebooklm", "version": "3.4.4"}
protocolVersion: 2024-11-05
capabilities: ['experimental', 'logging', 'prompts', 'resources', 'tools', 'extensions']
[response in 0.5s]

=== TOOLS/LIST ===
tool count: 39
tool names: ['refresh_auth', 'save_auth_tokens', 'batch', 'notebook_query',
 'chat_configure', 'notebook_query_start', 'notebook_query_status',
 'cross_notebook_query', 'download_artifact', 'export_artifact',
 'notebook_list', 'notebook_get', 'notebook_describe', 'notebook_create',
 'notebook_rename', 'notebook_delete', 'note', 'pipeline', 'research_start',
 'research_status', 'research_import', 'server_info',
 'notebook_share_status', 'notebook_share_public', 'notebook_share_invite',
 'notebook_share_batch', 'tag', 'source_add', 'source_list_drive',
 'source_sync_drive', 'source_rename', 'source_delete', 'source_describe',
 'source_get_content', 'studio_create', 'studio_status', 'studio_delete',
 'studio_revise', 'label']

=== READ-ONLY HEURISTIC ===
read-only-looking: 20 / 39
mutating-looking (19): ['refresh_auth', 'save_auth_tokens', 'notebook_query_start',
 'notebook_create', 'notebook_rename', 'notebook_delete', 'research_start',
 'research_import', 'notebook_share_status', 'notebook_share_public',
 'notebook_share_invite', 'notebook_share_batch', 'source_add',
 'source_sync_drive', 'source_rename', 'source_delete', 'studio_create',
 'studio_delete', 'studio_revise']

=== TOOLS WITH CONFIRM PARAM ===
confirm-gated: ['batch', 'notebook_delete', 'note', 'notebook_share_batch',
 'source_sync_drive', 'source_delete', 'studio_create', 'studio_delete',
 'studio_revise', 'label']
✅ Full handshake, 39 tools, 10 confirm-gated

Pass rate: 4 of 4. The server initializes in 0.5s, lists all 39 tools with schemas, declares six capability areas, and gates 10 destructive tools behind confirm parameters.

Run C - CLI and skill functional verification

$ nlm doctor
notebooklm-mcp-cli: 0.8.7
nlm: /Users/openclaw/.local/bin/nlm
notebooklm-mcp: /Users/openclaw/.local/bin/notebooklm-mcp
Default profile: not found
Google Chrome: installed
✅ Diagnostic runs clean

$ nlm skill install hermes --level project
✓ Installed SKILL.md (v0.8.7) to .hermes/skills/nlm-skill
 • SKILL.md
 • references/studio-prompting-guide.md
 • references/studio-prompt-examples.md
 • references/command_reference.md
 • references/troubleshooting.md
 • references/workflows.md
 • references/remote-mcp.md
✅ Skill installs for Hermes (7 files)

$ nlm skill install agents --level project
✓ Installed SKILL.md (v0.8.7) to .agents/skills/nlm-skill
✅ Skill installs for generic agents format

$ cd /tmp/notebooklm-review && uv run --python 3.12 pytest tests/ -q --tb=no
1120 passed, 39 skipped, 30 warnings in 24.11s
✅ Test suite green (1120/1159)

$ nlm --ai | head -5
# NLM CLI - AI Assistant Guide
You are interacting with `nlm`, a command-line interface for Google NotebookLM.
✅ AI-optimized documentation generates

Functional pass rate: 5 of 5. All testable surfaces work. The 39 skipped tests require live Google authentication and are correctly gated behind the @pytest.mark.e2e marker.

What the runs tell you

The install, MCP server protocol, CLI, skill installation, and test suite all work correctly. The only thing that cannot be verified without real Google credentials is whether the 39 tools actually communicate with NotebookLM and return correct data. Given that the project has 5,464 stars, 112 PyPI releases, 14 contributors fixing real bugs with specific PRs, and a 127-entry changelog documenting observed upstream API behavior changes, the functional layer is very likely working for authenticated users. But GearScope could not confirm this directly.

Setup Walkthrough

1. Install the package: uv tool install notebooklm-mcp-cli. This gives you two executables: nlm (CLI) and notebooklm-mcp (MCP server).

1. Authenticate: nlm login. This launches your default Chromium-family browser (Chrome, Arc, Brave, Edge, Chromium, or others). Log in to Google. The tool extracts cookies automatically and saves them to a profile. Check status with nlm login --check.

1. Configure your AI tool: nlm setup add claude-code (or gemini, cursor, windsurf, github-copilot, claude-desktop). This writes the correct MCP server config to the tool's expected location. For JSON-only tools, run nlm setup add json for an interactive wizard.

1. Install the agent skill (optional but recommended): nlm skill install claude-code (or hermes, cursor, codex, opencode, antigravity, agents). This writes the SKILL.md and six reference files to the agent's skill directory.

1. Verify everything: nlm doctor checks the installation, auth, browser, and tool configs in one pass.

Post-install gotcha: cookies expire after 2 to 4 weeks. The server has a 3-layer auto-recovery (CSRF refresh, token reload, headless browser auth), but if all layers fail, run nlm login again. The free tier has approximately 50 queries per day.

Alternatives

1. teng-lin/notebooklm-py - A Python library for NotebookLM that covers a similar internal-API surface. Lighter weight (library only, no MCP server or CLI). Better if you want to build your own interface rather than using a pre-built one. Lacks the agent skill and auto-setup features.

1. Direct browser automation (Playwright MCP + custom scripts) - Using microsoft/playwright-mcp to drive the NotebookLM web UI directly. More fragile than this project's RPC approach, but gives you full control and avoids depending on a third party's API reverse-engineering. Significantly more work to set up.

1. Google Gemini API (official) - If your use case is document Q&A, source-grounded chat, or content generation, Google's official Gemini API with grounded citations covers some of the same ground without the internal-API fragility. Does not replicate NotebookLM's specific features (Audio Overview podcasts, Deep Research, Studio content types).