mcp-notebooklm

MCP server that exposes Google NotebookLM notebooks as tools for AI assistants (opencode).

Thin wrapper over notebooklm-py using FastMCP.

What it implements

A stdio MCP server with four tools:

The service (src/mcp_notebooklm/service.py) wraps the async NotebookLMClient and applies two safety rails so the host LLM never hangs:

• Concurrency limit — one in-flight query at a time

(asyncio.Semaphore(1)), with a 10s queue timeout. If another query is running, the tool returns [RETRY_NEEDED] NotebookLM is busy... call again in ~60 seconds.

• Execution timeout — 60s hard cap on the underlying chat.ask(). Timeouts

and transport failures surface as [RETRY_NEEDED] / [ERROR] prefixes so the LLM can react instead of looping.

Authentication state is persisted to data/auth.json and reloaded on every request via NotebookLMClient.from_storage().

Prerequisites

• Python ≥ 3.12
• uv (recommended) or pipx
• A Google account with NotebookLM access

1. Install

From the project root:

uv sync

This installs the project (including the notebooklm-py[browser] extra, which pulls Playwright) and exposes the mcp-notebooklm console script.

2. Install Playwright browser (one-time)

notebooklm-py[browser] installs the Playwright Python package, but the Chromium browser binary must be downloaded separately.

uv run playwright install chromium

This is a one-time step (~170 MB) and must be done before the first login.

3. Authenticate with NotebookLM

The first run downloads Chromium (~170 MB) and opens a Google sign-in window. Auth state is written to data/auth.json and reused on subsequent calls.

# one-time login (interactive — finishes in the browser)
uv run --project notebooklm login --storage-path ./data/auth.json

# verify the session
uv run --project notebooklm auth check --test

The login command is provided by the upstream notebooklm-py CLI; see its README for browser options (--browser msedge, --browser-cookies chrome, multi-account --profile, etc.).

data/auth.json is git-ignored. Back it up somewhere safe — it is the only thing standing between you and a fresh login.

To refresh cookies silently (cron / launchd / systemd):

notebooklm auth refresh --quiet

4. Register with opencode

Add the server to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "notebooklm": {
      "command": [
        "uv",
        "run",
        "--project",
        "<your-path>/mcp-notebooklm",
        "mcp-notebooklm",
      ],
      "timeout": 120000,
      "type": "local",
    },
  },
}

Restart opencode. The four tools (list_notebooks, find_notebook, ask_notebook, generate_quiz) appear as notebooklm__* and are available immediately.

The timeout (120s) covers the worst-case ask path: 10s queue + 60s ask + overhead. Raise it if you see transport resets on slow networks.

5. Use it

From inside opencode (or any MCP host):

list all my NotebookLM notebooks

find the notebook about <topic>

ask notebook <notebook_id>: <question grounded in that notebook's sources>

Typical flow the LLM will follow:

1. list_notebooks() → choose the right notebook_id.
2. ask_notebook(id, question) → get a cited answer.
3. If the response starts with [RETRY_NEEDED], call the tool again.

Quiz generation

Generate structured quizzes that bypass NotebookLM's ~20 question limit by batching requests:

generate_quiz(
    notebook_id = "abc123",
    num_questions = 50,
    topic = "sorting algorithms",
    difficulty = "mixed",
    output_path = "~/quizzes/algorithms.json",
    cumulative = true,
    language = "es"
)

Parameters:

How batching works:

Questions are generated in batches of 15. For 50 questions, the tool makes 4 calls to NotebookLM (15 + 15 + 15 + 5), parses each response, and merges them into a single JSON. If a batch fails (timeout, parse error), it's skipped and failed_batches in metadata tells you how many were lost.

Output format:

{
  "metadata": {
    "notebook_id": "abc123",
    "notebook_title": "Algorithms",
    "generated_at": "2026-06-24T10:30:00Z",
    "topic": "sorting algorithms",
    "difficulty": "mixed",
    "total_questions": 50,
    "failed_batches": 0
  },
  "questions": [
    {
      "id": 1,
      "type": "multiple_choice",
      "question": "What is the average time complexity of quicksort?",
      "options": [
        {
          "text": "O(n)",
          "rationale": "Incorrect. Linear time only applies to specific cases like searching in unsorted arrays."
        },
        {
          "text": "O(n log n)",
          "rationale": "Correct. Quicksort averages O(n log n) with good pivot selection and balanced partitions."
        },
        {
          "text": "O(n²)",
          "rationale": "Incorrect. This is the worst-case complexity when the pivot selection is poor (e.g., already sorted array with first/last element as pivot)."
        },
        {
          "text": "O(log n)",
          "rationale": "Incorrect. Logarithmic time applies to operations like binary search, not full sorting algorithms."
        }
      ],
      "correct_answer": 1
    },
    {
      "id": 2,
      "type": "true_false",
      "question": "Mergesort is a stable sorting algorithm.",
      "correct_answer": true,
      "explanation": "Mergesort preserves the relative order of equal elements, making it stable."
    }
  ]
}

Cumulative mode:

When cumulative = true and output_path exists, new questions are appended to the existing array and IDs are renumbered sequentially. This lets you build up a question bank over multiple calls.

Project layout

src/mcp_notebooklm/
├── __init__.py
├── main.py        # entry point → server.main()
├── server.py      # FastMCP tool definitions (list, find, ask, generate_quiz)
└── service.py     # NotebookLMClient wrapper + concurrency / timeout guards + quiz generation
data/
└── auth.json      # notebooklm-py session storage (git-ignored)
pyproject.toml     # deps, entry point: mcp-notebooklm

Development

uv run ruff check src/        # lint
uv run flake8 src/           # style

Notes & limits

• The upstream library uses undocumented Google APIs — endpoints can break

without notice.

• Heavy usage is rate-limited; the 1-concurrent semaphore is intentional, not a

bug. Quiz generation with many questions will take time due to sequential batches.

• chat.ask is the only endpoint used. Source management, artifact generation,

etc. are not wired into the MCP surface.

• The server is stdio-only. For HTTP, look at the upstream notebooklm-py REST

server.