Content
# mcp-notebooklm
MCP server that exposes [Google NotebookLM](https://notebooklm.google.com/)
notebooks as tools for AI assistants (opencode).
Thin wrapper over [notebooklm-py](https://github.com/teng-lin/notebooklm-py)
using [`FastMCP`](https://github.com/modelcontextprotocol/python-sdk).
## What it implements
A stdio MCP server with four tools:
| Tool | Purpose |
| ------------------------------------------------ | -------------------------------------------------------------------------- |
| `list_notebooks()` | List every notebook with `id`, `title`, `source_count`. |
| `find_notebook(title)` | Case-insensitive partial match over notebook titles. |
| `ask_notebook(notebook_id, question)` | Ask a question; returns the grounded answer from NotebookLM. |
| `generate_quiz(notebook_id, num_questions, ...)` | Generate quiz JSON with multiple_choice / true_false questions in batches. |
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`](https://docs.astral.sh/uv/) (recommended) or `pipx`
- A Google account with NotebookLM access
## 1. Install
From the project root:
```bash
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.
```bash
# one-time login (interactive — finishes in the browser)
uv run notebooklm login --storage-path ./data/auth.json
```
The login command is provided by the upstream `notebooklm-py` CLI; see
[its README](https://github.com/teng-lin/notebooklm-py) 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):
```bash
notebooklm auth refresh --quiet
```
## 4. Register with opencode
Add the server to `~/.config/opencode/opencode.json`:
```jsonc
{
"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):
```text
list all my NotebookLM notebooks
```
```text
find the notebook about <topic>
```
```text
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:
```text
generate_quiz(
notebook_id = "abc123",
num_questions = 50,
topic = "sorting algorithms",
difficulty = "mixed",
output_path = "~/quizzes/algorithms.json",
cumulative = true,
language = "es"
)
```
**Parameters:**
| Param | Required | Default | Description |
| --------------- | -------- | --------------- | ----------------------------------------------------------------- |
| `notebook_id` | yes | — | Notebook to query |
| `num_questions` | yes | — | Total questions to generate |
| `topic` | no | `"all sources"` | Specific topic or full notebook |
| `difficulty` | no | `"mixed"` | `easy` / `medium` / `hard` / `mixed` |
| `output_path` | no | — | Save JSON to this path (creates directories if needed) |
| `cumulative` | no | `false` | If `true` and file exists, merge new questions with existing ones |
| `language` | no | `"es"` | Language for questions, options, and explanations |
**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:**
```json
{
"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
```text
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
```bash
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.
