# notebooklm-mcp

An [MCP](https://modelcontextprotocol.io) server that gives Claude (and any MCP-compatible agent) **full access to Google NotebookLM** — create notebooks, upload sources, ask questions, and generate audio overviews, quizzes, flashcards, mind maps, slide decks, videos, and reports.

![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green)

> **Stability note:** This server wraps [`notebooklm-py`](https://github.com/teng-lin/notebooklm-py), which reverse-engineers NotebookLM's unofficial API. It works well for personal and experimental use, but may break without notice if Google changes their API. Not recommended for production/business-critical workflows.

---

## What You Can Do

| Category | Examples |
|----------|---------|
| **Notebooks** | Create, rename, delete, list |
| **Sources** | Add URLs, upload files, web research, get full text |
| **Q&A** | Ask questions grounded in your sources |
| **Generate** | Audio overview, quiz, flashcards, mind map, slides, report, video |
| **Download** | Save any generated artifact to a local file |

---

## Quick Start

### Prerequisites

- Python 3.10+ — check with `python3 --version`
- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (recommended) — install with `curl -LsSf https://astral.sh/uv/install.sh | sh`
- A Google account with [NotebookLM](https://notebooklm.google.com) access

### 1. Clone the repo

```bash
git clone https://github.com/mulyg/notebooklm-mcp
cd notebooklm-mcp
```

### 2. Install dependencies

```bash
# With uv (recommended — handles venv automatically)
uv sync

# Or with pip
pip install "notebooklm-py[browser]" "mcp[cli]" pydantic httpx
playwright install chromium
```

> **Important:** The `playwright install chromium` step is required for authentication. If you skip it, the server will fail with a browser error.

### 3. Authenticate with Google

```bash
notebooklm login
```

This opens a browser window to sign in to your Google account. Your session is stored locally — you only need to do this once (sessions last ~30 days).

```bash
notebooklm auth check    # verify it worked
```

**What happens under the hood:** `notebooklm-py` uses browser automation (Playwright) to authenticate with Google and store your session cookies in `~/.notebooklm/`. No password is saved — only the session token.

---

## Connecting to Agent Environments

### Claude Code (CLI)

Add to `.mcp.json` in your project root, or to `~/.claude/claude_desktop_config.json` for global use:

```json
{
  "mcpServers": {
    "notebooklm": {
      "command": "uv",
      "args": ["run", "/path/to/notebooklm-mcp/server.py"]
    }
  }
}
```

### Claude Desktop — macOS

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "notebooklm": {
      "command": "uv",
      "args": ["run", "/Users/yourname/notebooklm-mcp/server.py"]
    }
  }
}
```

### Claude Desktop — Windows

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "notebooklm": {
      "command": "uv",
      "args": ["run", "C:\\Users\\YourName\\notebooklm-mcp\\server.py"]
    }
  }
}
```

> **Note:** On Windows, use double backslashes (`\\`) in JSON paths.

### Cursor / Windsurf / other MCP clients

Most MCP-compatible editors use the same `command` + `args` format. Point it at `server.py` using the pattern above. Consult your editor's MCP documentation for the config file location.

### Without uv

If you prefer plain Python:

```json
{
  "mcpServers": {
    "notebooklm": {
      "command": "python",
      "args": ["/path/to/notebooklm-mcp/server.py"]
    }
  }
}
```

Make sure the Python environment that has the dependencies installed is the one being used.

---

## How It Works

```
Claude / MCP client
       ↓  MCP protocol (stdio)
  server.py  (FastMCP)
       ↓  Python API
  notebooklm-py
       ↓  browser automation (Playwright)
  NotebookLM web API
       ↓
  Google's servers
```

`server.py` uses [FastMCP](https://github.com/jlowin/fastmcp) to expose 24 tools over the MCP stdio transport. Each tool call passes through `notebooklm-py`, which uses a headless Chromium browser to talk to NotebookLM's undocumented internal API.

---

## The Generate → Download Pattern

**Audio, quiz, flashcards, slides, reports, and videos are generated asynchronously.** Calling `generate_*` starts the generation task. Call `download_*` to save the result to disk once it's ready.

In practice, ask Claude to do both steps in a single prompt:

> "Generate a long deep-dive audio overview of my 'Product Strategy' notebook, then download it to ~/Downloads/strategy.mp3"

Claude will call `notebooklm_generate_audio` then `notebooklm_download_audio` automatically.

**Mind maps are the exception** — `notebooklm_generate_mind_map` returns the JSON data directly without a separate download step.

---

## Available Tools (24 total)

### Start Here

| Tool | What It Does |
|------|-------------|
| `notebooklm_list_notebooks` | See all your notebooks and their IDs |
| `notebooklm_create_notebook` | Create a new empty notebook |
| `notebooklm_rename_notebook` | Rename a notebook |
| `notebooklm_delete_notebook` | Delete a notebook permanently |

### Add Content to a Notebook

| Tool | What It Does |
|------|-------------|
| `notebooklm_add_url_source` | Add a web page, article, or YouTube URL |
| `notebooklm_add_file_source` | Upload a PDF, DOCX, TXT, audio, video, or image |
| `notebooklm_research` | Search the web and auto-import relevant sources |
| `notebooklm_list_sources` | See all sources in a notebook |
| `notebooklm_get_source_fulltext` | Read the text NotebookLM extracted from a source |
| `notebooklm_refresh_source` | Re-fetch a source if the original changed |

### Ask Questions

| Tool | What It Does |
|------|-------------|
| `notebooklm_ask` | Ask a question — answer is grounded in your sources |

### Generate Content (Step 1 of 2)

| Tool | Options |
|------|---------|
| `notebooklm_generate_audio` | format: deep-dive, brief, critique, debate · length: short, medium, long |
| `notebooklm_generate_quiz` | difficulty: easy, medium, hard |
| `notebooklm_generate_flashcards` | — |
| `notebooklm_generate_mind_map` | Returns JSON directly (no download needed) |
| `notebooklm_generate_slide_deck` | format: detailed, presenter |
| `notebooklm_generate_report` | template: briefing, study-guide, blog-post, custom |
| `notebooklm_generate_video` | format: explainer, brief, cinematic · style: auto, classic, whiteboard, kawaii, anime, watercolor, retro, heritage, paper-craft |

### Download Results (Step 2 of 2)

| Tool | Output |
|------|--------|
| `notebooklm_download_audio` | .mp3 |
| `notebooklm_download_quiz` | .json or .md (inferred from file extension) |
| `notebooklm_download_flashcards` | .json or .md |
| `notebooklm_download_mind_map` | .json |
| `notebooklm_download_slides` | .pdf or .pptx |
| `notebooklm_download_video` | .mp4 |

---

## Example Workflows

### Upload & Query

> "Create a notebook called 'AI Research', add this arxiv paper URL, then summarise the key findings."

### Study Mode

> "Generate flashcards and a quiz from my 'Biology 101' notebook. Make the quiz hard. Download both to ~/Downloads as JSON files."

### Podcast Creation

> "Generate a long deep-dive audio overview of my 'Product Strategy' notebook, then download it to ~/Downloads/strategy-podcast.mp3"

### Product Feedback Analysis

> "Create a 'Q1 Feedback' notebook. Add these 3 URLs from our support forum. Then ask: what are the top 5 complaints? Finally generate a briefing report."

### Research Pipeline

> "Research 'gen AI product management trends'. Import the results into my 'PM Research' notebook. Then generate a detailed slide deck from those sources."

### With Filesystem MCP (composability)

If you also have the [filesystem MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) active:

> "List all PDFs in ~/Documents/reports. Add each one to my 'Annual Reviews' notebook. Then ask: what were the key outcomes across all reports?"

---

## File Upload Guidelines

**Supported formats:** PDF, DOCX, TXT, audio (MP3, WAV, M4A), video (MP4, MOV), images (PNG, JPG)

**Approximate size limits:**
- Documents (PDF, DOCX, TXT): up to ~100 MB
- Audio/Video: up to ~500 MB (processing can take 5–10 minutes)
- Images: up to ~50 MB

**Tips:**
- For large PDFs, consider splitting into sections first
- `~` paths are supported (e.g. `~/Downloads/paper.pdf`)
- Video uploads are slower — extracting audio with `ffmpeg` first can speed things up

---

## Limitations & Caveats

- **Unofficial API** — `notebooklm-py` reverse-engineers NotebookLM's private API. Google may change it without notice, breaking the server.
- **Experimental only** — Not suitable for production or business-critical workflows.
- **Rate limiting** — NotebookLM has undocumented rate limits. If you hit errors, wait a few minutes and retry.
- **Audio generation is slow** — Expect 3–7 minutes per audio overview.
- **Research polling** — The `notebooklm_research` tool polls for up to 5 minutes. Deep research may occasionally time out; check `notebooklm_list_sources` afterward to verify.
- **No official Google support** — This project is not affiliated with or endorsed by Google.

---

## Session Management

**Check if your session is active:**
```bash
notebooklm auth check
```

**Re-authenticate (session expired):**
```bash
notebooklm login
```

**Reset and start fresh:**
```bash
rm -rf ~/.notebooklm/
notebooklm login
```

**Clean up test notebooks:**
> "List my notebooks and delete the ones with 'test' in the name."

---

## Troubleshooting

**`Authentication failed`**
Your session has expired. Run `notebooklm login` again.

**`Browser not installed` / Playwright error**
```bash
playwright install chromium
```

**`File not found`**
Use the full absolute path (e.g. `/Users/you/docs/paper.pdf` or `~/docs/paper.pdf`).

**`Output directory does not exist`**
Make sure the parent directory of your `output_path` exists before downloading.
```bash
mkdir -p ~/Downloads
```

**Audio/video generation times out**
Audio takes 3–7 minutes; video can take longer. Retry once — the task may still be running in NotebookLM. You can also check https://notebooklm.google.com directly to see if generation completed.

**`The underlying APIs changed`**
Check for a new release of [`notebooklm-py`](https://github.com/teng-lin/notebooklm-py) and update:
```bash
pip install --upgrade notebooklm-py
# or with uv:
uv sync --upgrade
```

**Python version too old**
```bash
python3 --version   # must be 3.10+
```
Install Python 3.10+ from [python.org](https://www.python.org/downloads/) or via your package manager.

---

## License

MIT