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 three 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().

Related MCP server: NotebookLM MCP Server

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. 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

3. 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 three tools (list_notebooks, find_notebook, ask_notebook) 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.

4. 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.

Project layout

src/mcp_notebooklm/
├── __init__.py
├── main.py        # entry point → server.main()
├── server.py      # FastMCP tool definitions
└── service.py     # NotebookLMClient wrapper + concurrency / timeout guards
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.

• Only chat.ask is exposed. Source management, artifact generation, etc. are not wired into the MCP surface yet.

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