# 🌌 Gemini Notebook MCP

<div align="center">

[![Version](https://img.shields.io/badge/version-2.1.0-blue.svg?style=for-the-badge)](https://github.com/vn002187444/gemini-notebook-mcp)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-Standard%20%26%20HTTP-00C7B7?style=for-the-badge&logo=fastapi&logoColor=white)](https://modelcontextprotocol.io/)
[![Patchright](https://img.shields.io/badge/Engine-Patchright%20Stealth-FF4088?style=for-the-badge)](https://github.com/Kaliiiiiiiiii-Venyx/patchright)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](./LICENSE)

**The Enterprise-Grade Model Context Protocol (MCP) Server for Google NotebookLM.**  
*Bridge the gap between Google's state-of-the-art Gemini grounding engine and your autonomous AI agent squad (Antigravity 2.0, Claude Code, Cursor, Windsurf, OpenCode, Jules).*

[Features](#-key-features) • [Installation](#-installation) • [Client Config](#-client-configuration) • [Tool Reference](#-mcp-tools-reference) • [Architecture](#-architecture) • [SDLC Ground-Truth](#-sdlc-ground-truth-protocol)

---

</div>

## 🚀 Overview

**Gemini Notebook MCP** (v2.1.0) is the next-generation, actively maintained MCP server connecting AI assistants directly to **Google NotebookLM**.

While traditional AI workflows consume hundreds of thousands of tokens injecting huge raw PDFs, transcripts, and codebases into context windows, **Gemini Notebook MCP** unlocks a **90% Token Reduction** through NotebookLM's native Map-Reduce retrieval. It provides autonomous AI agents with instant access to synthesized domain knowledge, full conversation histories, notes dumps, and **direct local file exports for Studio artifacts** (generated React/TSX components, Python scripts, study guides, reports, and audio podcasts).

---

## ✨ Key Features

### 🎨 1. Studio Panel Artifact Extraction & Auto-Downloads
- **`list_studio_items`**: Inspect all studio items generated by NotebookLM (Mind Maps, Study Guides, Briefing Docs, FAQs, Timelines, Audio Overviews, Custom Code Artifacts).
- **`get_studio_item`**: Read the full content and metadata of any studio artifact on demand.
- **`download_studio_item`**: Trigger native file downloads for any studio asset directly into your local workspace directory.
- **`export_studio_artifacts`**: Bulk export all studio assets (code `.tsx`, `.ts`, `.py`, `.json`, `.md`, images, audio) in one unified command.

### 💬 2. Complete Conversation & Thought-Chain Reconstruction
- **`get_chat_history`**: Retrieve complete structured chat turns between user and NotebookLM.
- **`export_chat_history`**: Dump entire notebook conversation transcripts to disk in structured JSON or Markdown formats.
- **Deep Grounding**: Extracts citations, referenced page fragments, and underlying model reasoning threads.

### 📝 3. Comprehensive Notes Knowledge Base
- **`list_notes`**: List all saved notes with tags and source anchors.
- **`get_note`**: Read individual note contents by ID or title.
- **`export_notes`**: Export all notes (e.g. 100+ research summaries) into markdown files for offline analysis and agent indexing.

### 🔍 4. Multimodal Sources & Media Retrieval
- **`list_sources`**: Retrieve all uploaded PDFs, Google Docs, YouTube transcripts, and web links.
- **`download_source_images`**: Extract and download source figures, architectural diagrams, screenshots, and visual assets directly to disk.
- **`add_source`**: Ingest new URLs, text snippets, or files programmatically into any notebook.

### 🎙️ 5. Audio Overview (Deep Dive Podcasts)
- **`generate_audio`**: Trigger generation of dual-host conversational podcast overviews.
- **`get_audio_status`**: Real-time progress monitoring (`pending`, `generating`, `ready`).
- **`download_audio`**: Download generated `.wav` / `.m4a` audio files directly to your storage.

### 🛡️ 6. Anti-Detection Stealth Engine (Patchright)
- Built on **Patchright** (hardened Playwright fork) with stealth flags, persistent human fingerprints, and zero browser automation leakage (`navigator.webdriver` patched).
- Headless execution with auto-fallback to Chromium channel.

---

## 🏗️ Architecture

```mermaid
flowchart TD
    subgraph Agents["Autonomous AI Agents & IDEs"]
        AG[Antigravity 2.0 Orchestrator]
        CL[Claude Desktop / Claude Code]
        CR[Cursor / Roo Code / Windsurf]
        OC[OpenCode Frontend & Jules Cloud]
    end

    subgraph MCP["Gemini Notebook MCP Server (v2.1.0)"]
        Router["JSON-RPC Tool Router (stdio / Streamable-HTTP)"]
        AuthMgr["Auth & Session Manager (State & Fingerprint)"]
        StudioExt["Studio Artifact & File Downloader Engine"]
        ChatHist["Chat & Thought-Chain Extractor"]
        NotesMgr["Notes & Ground-Truth Exporter"]
        PatchEng["Patchright Stealth Browser Core"]
    end

    subgraph Google["Google Cloud Infrastructure"]
        NLM["Google NotebookLM"]
        GeminiCore["Gemini 2.5 Pro / Flash Grounding Core"]
        Storage["NotebookLM Studio & Media Storage"]
    end

    Agents <-->|MCP Protocol| Router
    Router --> AuthMgr
    Router --> StudioExt
    Router --> ChatHist
    Router --> NotesMgr
    StudioExt & ChatHist & NotesMgr --> PatchEng
    PatchEng <-->|Secure Persistent Session| NLM
    NLM <--> GeminiCore
    NLM <--> Storage
```

---

## 📦 Installation

### Option 1: Run via NPX (Recommended)

```bash
npx gemini-notebook-mcp@latest
```

### Option 2: Clone & Build from Source

```bash
git clone https://github.com/vn002187444/gemini-notebook-mcp.git
cd gemini-notebook-mcp
npm install
npm run build
```

---

## 🔐 One-Click Authentication Setup

To authenticate with your Google Account once:

```bash
# In the repository root
npm run login
```

A dedicated browser window will launch. Log in to your Google Account and visit NotebookLM. The session state and credentials are automatically saved to your OS user data directory:
- **Windows**: `%LOCALAPPDATA%\notebooklm-mcp\Data\browser_state\state.json`
- **macOS**: `~/Library/Application Support/notebooklm-mcp/browser_state/state.json`
- **Linux**: `~/.local/share/notebooklm-mcp/browser_state/state.json`

Subsequent runs run completely **headless** and require no user interaction.

---

## ⚙️ Client Configuration

### 1. Antigravity 2.0 & AGY CLI

Add to your `mcp_servers` configuration in `~/.gemini/antigravity/mcp.json` or project configuration:

```json
{
  "mcpServers": {
    "notebooklm": {
      "command": "node",
      "args": ["d:/NotebookLM Knowledge/notebooklm-mcp/dist/index.js"],
      "env": {
        "BROWSER_CHANNEL": "chrome"
      }
    }
  }
}
```

### 2. Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "notebooklm": {
      "command": "npx",
      "args": ["-y", "gemini-notebook-mcp@latest"]
    }
  }
}
```

### 3. Cursor & Windsurf

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "notebooklm": {
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"]
    }
  }
}
```

---

## 🛠️ MCP Tools Reference

### 1. Studio Artifacts & Downloads (v2.1.0 New)

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `list_studio_items` | `notebook_id?` | Lists all generated studio artifacts (guides, code, audio, mindmaps). |
| `get_studio_item` | `item_id`, `notebook_id?` | Inspects full content and metadata of a studio item. |
| `download_studio_item` | `item_id`, `target_dir?` | Triggers download of a studio asset directly to disk. |
| `export_studio_artifacts`| `target_dir?`, `types?` | Batch exports all studio artifacts and generated code to target folder. |

### 2. Chat Conversation History & Thought Extraction (v2.1.0 New)

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `get_chat_history` | `notebook_id?`, `limit?` | Reconstructs the notebook conversation turns with citations & thoughts. |
| `export_chat_history` | `output_path`, `format?` | Dumps the full chat history into a `.json` or `.md` file. |

### 3. Notes Knowledge Base (v2.1.0 New)

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `list_notes` | `notebook_id?` | Lists all notes created by user or generated by NotebookLM. |
| `get_note` | `note_id`, `notebook_id?` | Reads the markdown content of a specific note. |
| `export_notes` | `output_dir?` | Exports all notes as markdown files in the specified directory. |

### 4. Notebook & Source Management

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `list_notebooks` | `limit?` | Lists all accessible notebooks with title, URL, and IDs. |
| `select_notebook` | `notebook_id_or_url` | Sets the active notebook context for all subsequent queries. |
| `get_notebook` | `notebook_id?` | Returns metadata, sources count, and summary of the notebook. |
| `add_notebook` | `title` | Creates a new empty notebook. |
| `remove_notebook` | `notebook_id` | Deletes a notebook. |
| `add_source` | `type`, `url?`, `text?` | Adds a URL, text, or file source to the active notebook. |
| `list_sources` | `notebook_id?` | Lists all ingested sources and their processing status. |
| `download_source_images`| `output_dir?` | Downloads source figures, images, and diagrams to disk. |

### 5. Grounded Q&A & Audio Overviews

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `ask_question` | `question`, `session_id?` | Ask a grounded question against notebook sources with full citations. |
| `generate_audio` | `notebook_id?` | Starts generating an AI Audio Overview (Deep Dive conversation). |
| `get_audio_status` | `notebook_id?` | Returns audio generation progress and completion status. |
| `download_audio` | `output_path` | Downloads the generated audio podcast file. |

---

## 🎯 SDLC Ground-Truth Protocol

When working in an agentic pair-programming workflow (e.g. Antigravity 2.0 SDLC), use the **NotebookLM Ground-Truth & Map-Reduce Protocol**:

1. **Avoid Raw Dumps**: Never load 50,000 lines of documentation or legacy code directly into your prompt. Ingest it as a NotebookLM source.
2. **4-Pass Deep Inquiry**: Use `ask_question` to query core logic, architecture schemas, and edge cases.
3. **Studio Asset Pull**: Use `export_studio_artifacts` to pull all code snippets (.tsx, .py, .ts) and assets synthesized by NotebookLM directly into the local repo (`docs/nlm_ground_truth_code/`).
4. **Zero Hallucination Verification**: Cross-reference generated code against the DOM-level citations returned by `get_chat_history`.

---

## 👨‍💻 Development & Testing

```bash
# Watch mode for rapid TypeScript development
npm run dev

# Run full TypeScript check and build
npm run check

# Code formatting & linting
npm run format
npm run lint
```

---

## 📄 License & Acknowledgements

- Licensed under the **[MIT License](./LICENSE)**.
- Built for the autonomous AI development era by **vn002187444**.
- Special thanks to the original `notebooklm-mcp` prototype foundations by Gérôme Dexheimer.