Google Notebook MCP Gateway

A secure, zero-credential-export Model Context Protocol (MCP) gateway connecting AI coding agents to your private Google Notebook knowledge bases (formerly NotebookLM).

Quickstart • Wiki • Supported Clients • Tool Reference • Documentation • Security Model

Overview

Google Notebook MCP brings the grounded reasoning, multi-document synthesis, and citation capabilities of Google NotebookLM directly into your AI development workflow (Claude Code, Cursor, Windsurf, Cline, Antigravity IDE, Zed).

Unlike traditional API wrappers or unofficial scrapers that ask you to paste session cookies into configuration files, this gateway operates under a strict Zero-Credential Export architecture:

• All upstream Google requests execute inside Google Chrome's native network process via a Manifest V3 companion extension.

• Google session cookies (SID, HSID, SSID), CSRF tokens (SNlM0e), and hardware Device Bound Session Credentials (DBSC) never leave Chrome's native memory.

• Credentials are never written to disk, never sent across local IPC sockets, and never visible to AI client prompt logs or transcripts.

Related MCP server: notebooklm-mcp-server

Architecture

flowchart TD
    subgraph ClientLayer["AI Coding Assistant"]
        Client["Claude Code / Cursor / Windsurf / Cline"]
    end

    subgraph MCPGateway["MCP Gateway Layer"]
        Facade["MCP stdio Facade (cli.py mcp)"]
        Broker["Broker Daemon (Unix Socket / Named Pipe)"]
        Journal["SQLite WAL Mutation Journal"]
        Allowlist["Allowlist Authorization (allowlist.json)"]
        Scrubber["Zero-Leakage Secret Scrubber (secret_scrubber.py)"]
    end

    subgraph NativeBridge["Native Messaging Bridge"]
        NativeHost["Python Native Messaging Host (native_host.py)"]
    end

    subgraph BrowserLayer["Google Chrome (DBSC / TPM Containment)"]
        MV3["Companion Extension (MV3 Background Service Worker)"]
        ChromeNet["Chrome Native Network Stack (fetch credentials: 'include')"]
        NotebookLM["Google Notebook (notebook.google.com / notebooklm.google.com)"]
    end

    Client <-->|"JSON-RPC 2.0 (stdio)"| Facade
    Facade <-->|"Big-Endian Framed IPC"| Broker
    Broker <--> Journal
    Broker <--> Allowlist
    Broker <--> Scrubber
    Broker <-->|"Local Socket"| NativeHost
    NativeHost <-->|"Chrome stdio Framing (@I, <=512 KiB)"| MV3
    MV3 <-->|"Internal DOM fetch()"| ChromeNet
    ChromeNet <-->|"Authenticated TLS"| NotebookLM

    classDef secure fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    class BrowserLayer,Scrubber secure;

Key Features

• 9 Production MCP Tools: Grounded natural-language Q&A with Unicode citation spans, source cataloging, note creation/listing/deletion, and file ingestion.

• ADR-011 Interactive Session Lock: Enforces single-notebook locking per session, preventing accidental cross-notebook queries or modifications.

• Project Directory Binding (.notebook_mcp.json): Seamlessly binds local workspaces to their designated NotebookLM notebook with an interactive in-chat confirmation handshake.

• Scotty 3-Step Resumable Uploads: Upload PDFs, Markdown, Word documents, and text files directly into NotebookLM with automatic offset resumption and $\le 512\text{ KiB}$ IPC slicing.

• Conservative Mutation Journaling: SQLite WAL state machine guarantees zero duplicate writes and freezes ambiguous requests upon network disconnection.

• Cross-Platform: Built-in support for Linux, macOS, and Windows (including Windows Named Pipes and automatic path length bounds).

Quickstart

🚀 Zero-Friction Automated Onboarding (Recommended)

Run the autonomous onboarding orchestrator directly from the repository root:

git clone https://github.com/wdeldaybytebuster/google-notebook-mcp.git
cd google-notebook-mcp

# Run the 6-stage autonomous onboarding wizard
python3 install_and_onboard.py

# Or via the CLI if installed:
gemini-notebook-mcp onboard

The orchestrator automatically:

1. Detects your compatible Chromium browser (bypassing ChromeOS Garcon bridges and configuring Wayland flags).

2. Registers the Chrome Native Messaging Host manifests across global and profile scopes.

3. Pre-seeds Developer mode and launches Chrome directly at chrome://extensions.

4. Injects or guides 1-click loading of the companion extension (with clipboard path assist) and verifies service_worker.js.

5. Navigates automatically to notebook.google.com with the companion extension already active.

6. Discovers all your notebooks and interactively seeds allowlist.json and .notebook_mcp.json.

Manual Step-by-Step Setup

1. Install

git clone https://github.com/wdeldaybytebuster/google-notebook-mcp.git
cd google-notebook-mcp

# Using pip:
pip install -e .

# Or using uv:
uv sync

2. Register Chrome Native Messaging Host

Automatically registers the gateway bridge with Chrome:

gemini-notebook-mcp install

3. Load Companion Extension in Chrome

1. Open Chrome and navigate to chrome://extensions.

2. Enable Developer mode (toggle in the top-right).

3. Click Load unpacked and select the src/extension/ directory from this repository.

4. Copy the generated Extension ID (e.g., abcdefghijklmnop...). If it differs from the default, run:

   gemini-notebook-mcp install --extension-id <COPIED_EXTENSION_ID>

4. Launch Gateway & Dedicated Browser

gemini-notebook-mcp launch

5. Authorize Your Notebooks

Run the interactive allowlist wizard to choose which notebooks your AI agents can access:

gemini-notebook-mcp allowlist seed

Client Configuration

Add the gateway to your favorite AI coding environment:

Claude Code

Run in your terminal:

claude mcp add gemini-notebook -- python3 -m mcp_gateway.cli mcp

Cursor (.cursor/mcp.json or Global Settings)

{
  "mcpServers": {
    "gemini-notebook": {
      "command": "python3",
      "args": ["-m", "mcp_gateway.cli", "mcp"],
      "env": {
        "MCP_BROKER_SOCKET": "/tmp/notebooklm-mcp-broker.sock",
        "UV_THREADPOOL_SIZE": "3"
      }
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "gemini-notebook": {
      "command": "python3",
      "args": ["-m", "mcp_gateway.cli", "mcp"],
      "env": {
        "MCP_BROKER_SOCKET": "/tmp/notebooklm-mcp-broker.sock"
      }
    }
  }
}

Cline / Roo Code (cline_mcp_settings.json)

{
  "mcpServers": {
    "gemini-notebook": {
      "command": "python3",
      "args": ["-m", "mcp_gateway.cli", "mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

For detailed instructions on other clients (Zed, Antigravity IDE, Neovim), see the Client Configuration Guide.

MCP Tool Reference

Full schema parameters and error envelopes are documented in the Tools Reference.

Project-Level Notebook Binding

When working inside a project repository, the gateway can automatically remember which NotebookLM knowledge base belongs to that project:

1. When calling select_notebook, setting save_for_project: true (the default) creates .notebook_mcp.json in your project root.

2. At the start of a chat, the AI assistant calls list_notebooks, discovers your project setting, and performs a conversational handshake:

   *"This project is configured to use notebook 'Project Docs'. Would you like to use this notebook, or select another from your allowlist?"*

3. Once confirmed, your session is locked and protected against accidental cross-notebook tampering.

Documentation

• GitHub Wiki: Comprehensive online wiki with interactive quickstarts, client guides, and FAQs.

• Getting Started Guide: Full walkthrough for Linux, macOS, and Windows.

• Client Configuration: Setup guides for all major AI coding agents.

• Tools Reference: Complete parameter reference, types, and error envelopes.

• Troubleshooting & FAQs: Diagnosing native messaging, permissions, and platform quirks.

• Security Architecture: Deep dive into TPM/DBSC containment and secret scrubbing.

• Architecture Decision Records: The 17 core architectural invariants (ADR-001 through ADR-017).

• GitHub Launch Completion Report: Full project ledger and security audit from the public repository launch.

Contributing

Contributions, bug reports, and suggestions are welcome! Please read our Contributing Guide and Code of Conduct before opening a pull request.

Security Vulnerability Reporting

If you discover a potential security vulnerability, please refer to our Security Policy to report it responsibly.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.