gemini-notebook-mcp-cli

Imported from midnghtsapphire/revvel-standards (mcp-servers/gemini-notebook-mcp-cli/AGENTS.md). Install upstream with npx skills add midnghtsapphire/revvel-standards --skill gemini-notebook-mcp-cli. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

Gemini Notebook (formerly Google NotebookLM) MCP Server & CLI - Provides programmatic access to Gemini Notebook (notebook.google.com) via both a Model Context Protocol server and a comprehensive command-line interface.

Tested with personal/free tier accounts. May work with Google Workspace accounts but has not been tested.

Development Commands

# Install dependencies
uv tool install .

# Reinstall after code changes (ALWAYS clean cache first)
uv cache clean && uv tool install --force .

# Run the MCP server (stdio)
notebooklm-mcp

# Run with Debug logging
notebooklm-mcp --debug

# Run as HTTP server
notebooklm-mcp --transport http --port 8000

# Run tests
uv run pytest

# Run a single test
uv run pytest tests/test_file.py::test_function -v

Python requirement: >=3.11

Authentication (SIMPLIFIED!)

You only need to provide COOKIES! The CSRF token and session ID are now automatically extracted when needed.

Method 1: Chrome DevTools MCP (Recommended)

Option A - Fast (Recommended): Extract CSRF token and session ID directly from network request - no page fetch needed!

# 1. Navigate to NotebookLM page
navigate_page(url="https://notebook.google.com/")

# 2. Get a batchexecute request (any NotebookLM API call)
get_network_request(reqid=<any_batchexecute_request>)

# 3. Save with all three fields from the network request:
save_auth_tokens(
    cookies=<cookie_header>,
    request_body=<request_body>,  # Contains CSRF token
    request_url=<request_url>      # Contains session ID
)

Option B - Minimal (slower first call): Save only cookies, tokens extracted from page on first API call

save_auth_tokens(cookies=<cookie_header>)

Method 2: Environment Variables

Token Expiration

• Cookies: Stable for weeks, but some rotate on each request
• CSRF token: Auto-refreshed on each client initialization
• Session ID: Auto-refreshed on each client initialization
• Build label (bl): Auto-extracted during login and CSRF refresh; stays current with Google's build

When API calls fail with auth errors, re-extract fresh cookies from Chrome DevTools.

Architecture

src/notebooklm_tools/
├── __init__.py          # Package version
├── services/            # Shared service layer (v0.3.0+)
│   ├── errors.py        # ServiceError, ValidationError, NotFoundError, etc.
│   ├── chat.py          # Chat/query logic
│   ├── downloads.py     # Artifact downloading
│   ├── exports.py       # Google Docs/Sheets export
│   ├── notebooks.py     # Notebook CRUD + describe
│   ├── notes.py         # Note CRUD
│   ├── research.py      # Research start/poll/import
│   ├── sharing.py       # Public link, invite, status
│   ├── sources.py       # Source add/list/sync/delete
│   └── studio.py        # Artifact creation, status, rename, delete
├── cli/                 # CLI commands and formatting (thin wrapper)
├── mcp/                 # MCP server + tools (thin wrapper)
│   ├── server.py        # FastMCP server facade
│   └── tools/           # Modular tool definitions per domain
├── core/                # Low-level API client (no business logic)
│   ├── client.py        # Internal batchexecute API calls
│   ├── constants.py     # Code-name mappings (CodeMapper class)
│   └── auth.py          # AuthManager for profile-based token caching
└── utils/
    ├── config.py        # Configuration and storage paths
    └── cdp.py           # Chrome DevTools Protocol for cookie extraction

Layering Rules (v0.3.0+):

• cli/ and mcp/ are thin wrappers: they handle UX concerns (prompts, spinners, JSON responses) and delegate to services/
• services/ contains all business logic, validation, and error handling. Returns typed dicts.
• cli/ and mcp/ must NOT import from core/ directly — always go through services/
• services/ raises ServiceError/ValidationError — never raw exceptions

Storage Structure (~/.notebooklm-mcp-cli/):

├── config.toml                    # CLI settings (default_profile, output format)
├── aliases.json                   # Notebook aliases
├── profiles/<name>/auth.json      # Per-profile credentials and email
├── chrome-profile/                # Chrome session (single-profile/legacy)
└── chrome-profiles/<name>/        # Chrome sessions (multi-profile)

Executables:

• nlm - Command-line interface
• notebooklm-mcp - The Gemini Notebook MCP server executable

Configured MCP name: gemini-notebook-mcp (the executable name remains notebooklm-mcp for compatibility). Claude Desktop setup detects regular and Relay AI/3P profiles, never creates missing profiles, and refuses to write while the selected Claude instance is running. User-level skill installation also requires the target tool to be detected.

MCP Tools Provided

IMPORTANT - Operations Requiring Confirmation:

• notebook_delete requires confirm=True - deletion is IRREVERSIBLE
• source_delete requires confirm=True - deletion is IRREVERSIBLE
• source_sync_drive requires confirm=True - always show stale sources first via source_list_drive
• All studio creation tools require confirm=True - show settings and get user approval first
• studio_delete requires confirm=True - list artifacts first via studio_status, deletion is IRREVERSIBLE
• studio_revise requires confirm=True - creates a new artifact with revisions applied
• note_delete requires confirm=True - deletion is IRREVERSIBLE

Features NOT Yet Implemented

None - all Gemini Notebook features that can be accessed programmatically are implemented.

Troubleshooting

"401 Unauthorized" or "403 Forbidden"

• Cookies or CSRF token expired
• Re-extract from Chrome DevTools

"Invalid CSRF token"

• The at= value expired
• Must match the current session

Empty notebook list

• Session might be for a different Google account
• Verify you're logged into the correct account

Rate limit errors

• Free tier: ~50 queries/day
• Wait until the next day or upgrade to Plus

Documentation

API Reference

For detailed API documentation (RPC IDs, parameter structures, response formats), see:

docs/API_REFERENCE.md

This includes:

• All discovered RPC endpoints and their parameters
• Source type structures (URL, text, Drive)
• Studio content creation (audio, video, reports, etc.)
• Research workflow details
• Mind map generation process
• Source metadata structures

Only read API_REFERENCE.md when:

• Debugging API issues
• Adding new features
• Understanding internal API behavior

MCP Test Plan

For comprehensive MCP tool testing, see:

docs/MCP_CLI_TEST_PLAN.md

This includes:

• Step-by-step test cases for all 43 MCP tools and CLI commands
• Authentication and basic operations tests
• Source management and Drive sync tests
• Studio content generation tests (audio, video, infographics, etc.)
• Quick copy-paste test prompts for validation

Use this test plan when:

• Validating MCP server functionality after code changes
• Testing new tool implementations
• Debugging MCP tool issues

Contributing

When adding new features:

1. Use Chrome DevTools MCP to capture the network request
2. Document the RPC ID in docs/API_REFERENCE.md
3. Add the param structure with comments
4. Add the low-level API method in core/client.py
5. Add business logic in the appropriate services/*.py module
6. Add a thin wrapper in mcp/tools/*.py (for MCP) and cli/commands/*.py (for CLI)
7. Write unit tests for the service function in tests/services/
8. Update the "Features NOT Yet Implemented" checklist
9. Add test case to docs/MCP_TEST_PLAN.md

License

MIT License