NotebookLM MCP Architecture

An MCP server that enables AI coding agents (Claude Code, Codex, Cursor) to query Google NotebookLM for zero-hallucination, source-grounded answers powered by Gemini 2.5. The server automates a headless Chromium browser via Patchright to interact with the NotebookLM web UI, managing authentication, sessions, and a local notebook library. It communicates with clients over stdio using the Model Context Protocol, and can be exposed over HTTP/SSE via supergateway when containerized.

Author: Gerome Dexheimer — License: MIT — Source: github.com/PleasePrompto/notebooklm-mcp

Component Classification

Component	Class	Role
MCP Server (`index.ts`)	Primary	Entry point; registers tools, resources, and request handlers
Tool Handlers (`tools/handlers.ts`)	Primary	Implements all 17 MCP tool operations
Session Manager (`session/`)	Primary	Browser session lifecycle, pooling, timeout cleanup
Auth Manager (`auth/`)	Primary	Google login, cookie persistence, state validation
Notebook Library (`library/`)	Secondary	Local JSON library of saved NotebookLM URLs with metadata
Tool Definitions (`tools/definitions/`)	Secondary	MCP tool schemas and dynamic descriptions
Resource Handlers (`resources/`)	Secondary	MCP resource endpoints for library access
Settings Manager (`utils/settings-manager.ts`)	Auxiliary	Tool profile filtering (minimal/standard/full)
Stealth Utils (`utils/stealth-utils.ts`)	Auxiliary	Human-like typing, mouse movements, random delays
Cleanup Manager (`utils/cleanup-manager.ts`)	Auxiliary	Deep system scan and removal of all NotebookLM data
CLI Handler (`utils/cli-handler.ts`)	Auxiliary	`npx notebooklm-mcp config` subcommand
Google NotebookLM	External	Web application providing Gemini 2.5 Q&A over uploaded documents
Patchright / Chromium	External	Stealth browser automation (Playwright fork)
supergateway	External	Bridges stdio MCP to HTTP/SSE for Docker deployment

MCP Tools

Source Files

Language

TypeScript

Runtime

Node.js 18+

Transport

stdio / HTTP+SSE

Browser Engine

Patchright (Chromium)

2. Runtime Architecture

Diagram A — Runtime Request Flow

Request Flow: ask_question

Claude Code sends a tools/call JSON-RPC request over stdio (or HTTP via supergateway in Docker mode).
The MCP Server dispatches to ToolHandlers.handleAskQuestion().
The handler resolves the notebook URL from the library (by ID, URL, or active notebook fallback).
SessionManager returns an existing BrowserSession or creates a new one using the SharedContextManager, which loads persisted auth state into a Patchright browser context.
The BrowserSession navigates to the NotebookLM URL, types the question with human-like behavior (stealth utils), and waits for the Gemini 2.5 answer to fully render.
The answer is extracted from the DOM, appended with a follow-up reminder, and returned as a JSON tool result.

3. Internal Module Map

graph TD subgraph Entry INDEX["index.ts
MCP Server"] end subgraph Tools DEFS["tools/definitions.ts"] HAND["tools/handlers.ts"] D_AQ["definitions/ask-question.ts"] D_NM["definitions/notebook-management.ts"] D_SM["definitions/session-management.ts"] D_SY["definitions/system.ts"] end subgraph Session SMGR["session-manager.ts"] BSESS["browser-session.ts"] SCTX["shared-context-manager.ts"] end subgraph Auth AMGR["auth-manager.ts"] end subgraph Library NLIB["notebook-library.ts"] LTYP["library/types.ts"] end subgraph Utils LOG["logger.ts"] STL["stealth-utils.ts"] CLN["cleanup-manager.ts"] PGU["page-utils.ts"] SET["settings-manager.ts"] CLI["cli-handler.ts"] end subgraph Config CFG["config.ts"] TYP["types.ts"] ERR["errors.ts"] end INDEX --> DEFS INDEX --> HAND INDEX --> SMGR INDEX --> AMGR INDEX --> NLIB INDEX --> SET INDEX --> CLI DEFS --> D_AQ DEFS --> D_NM DEFS --> D_SM DEFS --> D_SY HAND --> SMGR HAND --> AMGR HAND --> NLIB HAND --> CLN SMGR --> BSESS SMGR --> SCTX SMGR --> AMGR BSESS --> SCTX BSESS --> STL BSESS --> PGU AMGR --> STL SCTX --> AMGR

4. Storage Model

All persistent data is stored on the local filesystem under cross-platform paths managed by the env-paths library. In Docker, a named volume maps to /data.

Path	Format	Contents
`~/.local/share/notebooklm-mcp/browser_state/state.json`	JSON	Saved browser cookies and localStorage for Google auth
`~/.local/share/notebooklm-mcp/browser_state/session.json`	JSON	Session metadata (timestamps, message counts)
`~/.local/share/notebooklm-mcp/chrome_profile/`	Directory	Persistent Chromium user profile (fingerprint, cache)
`~/.local/share/notebooklm-mcp/chrome_profile_instances/`	Directory	Cloned profiles for isolated multi-instance sessions
`~/.config/notebooklm-mcp/library.json`	JSON	Notebook library: URLs, names, tags, usage counts
`~/.config/notebooklm-mcp/settings.json`	JSON	Tool profile setting (minimal/standard/full)

Docker volume: The notebooklm_data named volume persists auth state and library data across container restarts. It is mapped to /root/.local/share/notebooklm-mcp inside the container.

5. Public Interfaces (MCP Tools)

The server exposes up to 17 MCP tools, filtered by the active profile. Three profiles are available: minimal (5 tools), standard (11 tools), and full (17 tools).

Core Tools (minimal profile)

Tool	Parameters	Description
`ask_question`	`question` (required), `session_id`, `notebook_id`, `notebook_url`, `show_browser`, `browser_options`	Ask NotebookLM a question; returns Gemini 2.5 answer grounded in notebook sources
`get_health`	—	Returns auth status, active sessions, configuration summary
`list_notebooks`	—	Lists all notebooks in the local library
`select_notebook`	`id`	Sets the active default notebook for subsequent queries
`get_notebook`	`id`	Fetches metadata for a specific notebook by ID

Library & Sync Tools (standard profile adds these)

Tool	Parameters	Description
`setup_auth`	`show_browser`, `force_fresh`, `browser_options`	Opens browser for manual Google login; persists auth state
`list_sessions`	—	Returns active browser sessions with age and message counts
`add_notebook`	`url`, `name`, `description`, `topics[]`, `tags[]`	Adds a NotebookLM URL to the local library with metadata
`update_notebook`	`id`, optional fields	Modifies metadata fields on a library notebook
`search_notebooks`	`query`	Full-text search across notebook names, descriptions, topics, tags
`replace_bundle_source`	`bundle_path`, `source_name`, `remove_existing`, notebook selectors, browser options	Replaces a single source document in a NotebookLM notebook from a local file

Advanced Tools (full profile adds these)

Tool	Parameters	Description
`cleanup_data`	`confirm`, `preserve_library`	Deep system scan; previews or deletes all NotebookLM data
`re_auth`	`show_browser`, `browser_options`	Full re-authentication: closes sessions, clears data, fresh login
`remove_notebook`	`id`	Removes a notebook from the library and closes its sessions
`reset_session`	`session_id`	Resets a session's chat history without closing the browser
`close_session`	`session_id`	Closes a specific browser session and frees resources
`get_library_stats`	—	Aggregate statistics: total notebooks, usage counts, tags

MCP Resources

URI	Description
`notebooklm://library`	JSON representation of the full library (active notebook, stats, all entries)
`notebooklm://library/{id}`	Metadata for a specific notebook (template with completion support)

6. Repository Structure

notebooklm-mcp/
  package.json              # npm package config, scripts, dependencies
  tsconfig.json             # TypeScript compiler options (ES2022, Node16)
  Dockerfile                # Multi-stage: node:20-slim + Chromium + supergateway
  docker-compose.yml        # Service definition with hosting_web network
  README.md                 # Usage guide and installation instructions
  CHANGELOG.md              # Version history (1.0.0 through unreleased)
  LICENSE                   # MIT license
  docs/
    tools.md                # Tool reference documentation
    usage-guide.md           # Patterns and workflow tips
    configuration.md         # Environment variable reference
    troubleshooting.md       # Common issues and solutions
  scripts/                  # Utility scripts
  src/
    index.ts                # MCP server entry point (NotebookLMMCPServer class)
    config.ts               # Configuration system (defaults + env overrides)
    types.ts                # Global TypeScript type definitions
    errors.ts               # Custom error classes (RateLimitError, etc.)
    auth/
      auth-manager.ts       # Google auth: login, state persistence, validation
    session/
      session-manager.ts    # Session pool lifecycle, timeout cleanup
      browser-session.ts    # Single browser session: ask, reset, bundle sync
      shared-context-manager.ts  # Shared Patchright browser context singleton
    library/
      notebook-library.ts   # JSON-backed notebook library CRUD
      types.ts              # Library-specific type definitions
    tools/
      index.ts              # Re-exports definitions + handlers
      definitions.ts        # Aggregates tool schemas from sub-modules
      handlers.ts           # All 17 tool handler implementations
      definitions/
        ask-question.ts     # Dynamic ask_question schema with library context
        notebook-management.ts  # add/update/remove/search/select schemas
        session-management.ts   # list/close/reset session schemas
        system.ts           # health, auth, cleanup schemas
    resources/
      resource-handlers.ts  # MCP resource + template handlers
    utils/
      logger.ts             # Structured logging utility
      stealth-utils.ts      # Human-like typing, mouse, delays
      cleanup-manager.ts    # Deep system cleanup scanner
      page-utils.ts         # DOM interaction helpers (wait for answer, etc.)
      settings-manager.ts   # Tool profile filtering + persistence
      cli-handler.ts        # CLI config subcommand handler

7. Deployment & Operations

Local (npx / CLI)

The simplest deployment mode. The MCP server runs as a child process of the AI agent, communicating over stdio.

# Install as MCP server for Claude Code
claude mcp add notebooklm npx notebooklm-mcp@latest

# Or run directly
npx notebooklm-mcp@latest

# Configure tool profiles
npx notebooklm-mcp config set profile minimal

Docker

The Dockerfile builds a node:20-slim image with Chromium system dependencies, Patchright's bundled Chromium, and supergateway for HTTP/SSE transport.

Setting	Value
Base image	`node:20-slim`
Exposed port	`3300` (supergateway HTTP/SSE)
Entry command	`supergateway --port 3300 --stdio "node /app/dist/index.js"`
Named volume	`notebooklm_data` at `/root/.local/share/notebooklm-mcp`
Network	`hosting_web` (external, Traefik-connected)
Restart policy	`unless-stopped`

Environment Variables

Variable	Default	Description
`HEADLESS`	`true`	Run Chromium in headless mode
`MAX_SESSIONS`	`3`	Maximum concurrent browser sessions
`SESSION_TIMEOUT`	`900`	Session inactivity timeout in seconds
`NOTEBOOK_URL`	—	Default NotebookLM notebook URL
`AUTO_LOGIN_ENABLED`	`false`	Enable automatic Google login
`LOGIN_EMAIL`	—	Google email for auto-login
`LOGIN_PASSWORD`	—	Google password for auto-login
`STEALTH_ENABLED`	`true`	Enable human-like browser behavior
`NOTEBOOKLM_PROFILE`	`standard`	Tool profile: minimal, standard, or full
`NOTEBOOKLM_DISABLED_TOOLS`	—	Comma-separated list of tools to disable

# Build and start
cd /home/rod/_rod/_notebooklm-mcp
docker compose up -d --build

# View logs
docker logs -f notebooklm-mcp

# Re-authenticate (Docker helper)
docker exec notebooklm-mcp xvfb-reauth

8. Dependencies

Runtime Dependencies

Package	Version	Purpose
`@modelcontextprotocol/sdk`	^1.0.0	MCP server framework (Server, StdioServerTransport, types)
`patchright`	^1.48.2	Stealth Playwright fork for browser automation with anti-detection
`zod`	^3.22.0	Runtime schema validation
`dotenv`	^16.4.0	Environment variable loading from .env files
`env-paths`	^3.0.0	Cross-platform XDG-compliant data/config directory paths
`globby`	^14.1.0	Advanced glob file pattern matching (cleanup scanner)

Dev Dependencies

Package	Version	Purpose
`typescript`	^5.3.3	TypeScript compiler (target: ES2022)
`tsx`	^4.7.0	TypeScript execution for development
`@types/node`	^20.11.0	Node.js type definitions

System Dependencies (Docker)

Package	Purpose
`xvfb`	Virtual framebuffer for headless Chromium rendering
`[email protected]`	Bridges stdio MCP server to HTTP/SSE endpoints
Chromium system libs (20+ packages)	GTK, NSS, ALSA, Cairo, etc. required by Patchright's Chromium

9. Constraints & Risks

Item	Severity	Details
Browser automation fragility	Medium	The server scrapes the NotebookLM web UI via DOM selectors. Google UI changes can break question submission or answer extraction at any time.
Rate limiting	Medium	Free Google accounts are limited to ~50 queries/day per account. The server detects rate limits and suggests account switching via `re_auth`.
Google account risk	Medium	Automated browser usage may trigger Google's abuse detection. Stealth mode (human-like typing, random delays) mitigates this, but a dedicated Google account is recommended.
No official API	High	NotebookLM has no public API. This project relies entirely on browser automation of the web UI, making it inherently brittle.
Auth cookie expiry	Low	Google session cookies expire after ~24 hours. The auth manager validates cookie age and prompts re-authentication when needed.
supergateway SSE reconnection	Low	The Dockerfile includes a runtime patch to supergateway to handle SSE reconnections gracefully (clears old transport before reconnecting).

Generated by /repo-architecture v2.0.0 on 2026-03-22. This document is auto-generated — regenerate after significant changes.