notebooklm-mcp: Instructions file for Gemini CLI

NotebookLM MCP Server - Project Context

This file provides the foundational context, architecture, and engineering standards for the NotebookLM MCP Server project.

Project Overview

The NotebookLM MCP Server is a Model Context Protocol (MCP) implementation that exposes the capabilities of Google NotebookLM to AI models. It facilitates deep integration of NotebookLM's notebook management, source ingestion, RAG-based querying, and studio content generation into AI-assisted workflows.

Key Technologies

• Runtime: Node.js (>=20)
• Language: TypeScript (strict)
• Package manager: pnpm (pinned via packageManager: "[email protected]"; use corepack enable && pnpm install)
• Framework: @modelcontextprotocol/sdk
• Bundler: tsup
• CLI: commander
• Validation: zod
• Testing: vitest + msw (100% statements/branches/functions/lines, enforced by CI)
• API Communication: Direct interaction with Google's internal batchexecute RPC endpoint via fetch.

Architecture

The project follows a modular SRP-respecting architecture centered around the MCP specification:

• Entry Points:
  • src/cli.ts: Handles CLI commands (serve, auth). Version read from package.json at runtime.
  • src/server.ts: Initializes the McpServer and orchestrates tool registration.
• Core Client (domain facade):
  • src/client.ts: NotebookLMClient — public surface for tools. Domain methods (listNotebooks, query, createAudioOverview, etc.) delegate infrastructure to the rpc/* collaborators.
• RPC layer (extracted 2026-05-17):
  • src/rpc/transport.ts: RpcTransport — HTTP POST/GET to batchexecute and query endpoints. Enforces response.ok, merges Set-Cookie via AuthState, wraps response.text() in a race-with-abort so slow bodies actually honor the timeout.
  • src/rpc/auth-state.ts: AuthState — owns tokens / csrfToken / sessionId / cookies. Provides a single-flight refreshOnce() mutex (concurrent callers share one refresh), reloadIfNewer() disk pickup, and persisted recordSessionId / recordCsrfToken / recordSetCookies writes.
  • src/rpc/wire.ts: Pure parsers — parseResponse (batchexecute envelope), extractTextFromBlocks (source content incl. tables), sourceTypeCode, and the studio parsers studioArtifactId / studioTypeName / studioDownloadUrl.
• Tools:
  • src/tools/: Directory containing modular tool definitions (e.g., notebook.ts, source.ts, query.ts, studio.ts).
  • src/tools/index.ts: Central registration point; also exports resolveSourceIds() (used by 9 studio tools) and clientResetSignal() (typed replacement for the legacy _client_action: "reset" string).
• Authentication:
  • src/auth.ts: Logic for token loading, saving (mode 0600), validation, and the manual auth flow. ~/.notebooklm-mcp/ is created with mode 0700.
  • src/browser-auth.ts: Launches Chrome with --remote-debugging-port=0 --remote-debugging-address=127.0.0.1 and discovers the OS-assigned port by parsing the DevTools listening on ws://127.0.0.1:NNNN/ stderr line. Drives it directly via the Chrome DevTools Protocol (CDP) over a raw ws WebSocket — no Puppeteer/Playwright dependency.