NotebookLM Claude Integration

Complete integration of Google NotebookLM with Claude AI through both Claude Desktop (MCP) and Claude Code (Plugin).

Status: Production-ready ✅ | Built: Dec 2024 | Tested: Fully functional

What This Is

This project provides two complete integrations for using NotebookLM with Claude:

1. Claude Desktop - MCP Server for conversational interface

2. Claude Code CLI - Plugin for development workflow

Both allow you to query your NotebookLM notebooks directly from Claude, getting citation-backed answers from Gemini without leaving your workflow.

Related MCP server: NotebookLM MCP Server

Quick Start

Project plan lives at docs/PROJECT_PLAN.md with topic-specific items under docs/plans/. CI details live at docs/CI.md.

Keep Pixi dependencies current (updates the lockfile, then installs from it):

pixi run pixi-sync

NotebookLM end-to-end integration (uses your local Chrome auth):

NOTEBOOK_IDS=pytest-patterns \
QUESTION="Summarize the key sources in this notebook." \
pixi run notebooklm-integration

AI Agent Step-by-Step (Codex CLI)

Use this sequence when an agent needs to verify the NotebookLM integration end-to-end.

1. Install and enable the MCP server:

   uv tool install notebooklm-mcp-server
   codex mcp add notebooklm-rpc notebooklm-mcp

2. Authenticate once (browser login) and persist cookies:

   pixi run notebooklm-auth-rpc

3. Run the full E2E test (downloads the skill from GitHub into a temp repo and queries a notebook):

   pixi run codex-skill-e2e

4. Optional overrides:

   NOTEBOOK_URL="https://notebooklm.google.com/notebook/<id>" \
   NOTEBOOK_NAME="My Test Notebook" \
   NOTEBOOK_DESC="Notebook for testing Codex + NotebookLM." \
   NOTEBOOK_ID="my-test-notebook" \
   pixi run codex-skill-e2e

AI Agent Step-by-Step (Codex SDK)

Use this sequence when a Codex SDK agent must validate the setup and produce a confirmed response.

1. Ensure Codex CLI + MCP are set up (same as CLI steps above).

2. Run the SDK verification (temp workspace, streaming output):

   SDK_ROOT=/tmp/codex-sdk-verify
   rm -rf "$SDK_ROOT" && mkdir -p "$SDK_ROOT"
   cd "$SDK_ROOT"
   
   cat <<'EOF' > package.json
   {
     "name": "codex-sdk-verify",
     "version": "0.1.0",
     "private": true,
     "type": "module",
     "scripts": { "run": "node run.mjs" },
     "dependencies": { "@openai/codex-sdk": "^0.77.0" }
   }
   EOF
   
   cat <<'EOF' > run.mjs
   import { Codex } from "@openai/codex-sdk";
   
   const prompt = [
     "Use the notebooklm-patterns skill.",
     "List all notebooks, then ask each notebook (via notebook_id) this question:",
     "'How can we improve the Codex implementation in this repo?'.",
     "Aggregate responses labeled by notebook name and include citations.",
    "If any notebook_query times out, retry once. If it still times out, record a timeout for that notebook and continue.",
   ].join(" ");
   
   const codex = new Codex();
   const thread = codex.startThread({
     workingDirectory: "/tmp/codex-skill-verify",
     sandboxMode: "read-only",
     approvalPolicy: "never",
   });
   
   const { events } = await thread.runStreamed(prompt);
   for await (const event of events) {
     if (event.type === "item.completed" && event.item?.type === "agent_message") {
       console.log(event.item.text);
     }
     if (event.type === "turn.failed") {
       console.error("Codex SDK turn failed:", event.error?.message ?? event.error);
     }
   }
   EOF
   
   npm install
   npm run run

For Claude Code (Plugin)

# 1. Ensure NotebookLM MCP server is configured
uv tool install notebooklm-mcp-server
claude mcp add notebooklm-rpc -- notebooklm-mcp

# 2. Add the plugin marketplace from GitHub
claude plugin marketplace add ray-manaloto/notebooklm-claude-integration

# 3. Install the plugin (project scope)
claude plugin install notebooklm@notebooklm-plugin --scope project

# 4. Verify installation
claude plugin marketplace list  # Should show: notebooklm-plugin
claude plugin list              # Should show: notebooklm

# 5. Restart Claude Code, then:
/nlm auth rpc                      # First-time authentication
/nlm list                          # List notebooks
/nlm ask "Your question"           # Query the notebook

For local development (if you cloned this repo):

claude plugin marketplace add .

For Claude Desktop (MCP)

npm install -g notebooklm-mcp

Alternate NotebookLM MCP (HTTP/RPC, jacob-bd)

This repo also supports the HTTP/RPC-based MCP server from jacob-bd/notebooklm-mcp, which exposes additional tools (notebook creation, Drive sync, Studio artifacts).

Install + auth:

uv tool install notebooklm-mcp-server
GOOGLE_ACCOUNT=ray.manaloto@gmail.com pixi run notebooklm-auth-rpc

Pixi task (recommended for repeatable runs):

pixi run notebooklm-auth-rpc

Override account:

GOOGLE_ACCOUNT=your@email pixi run notebooklm-auth-rpc

Register the MCP server:

codex mcp add notebooklm-rpc -- notebooklm-mcp

Notes:

• This server uses cookie extraction; persist cookies with save_auth_tokens.

• Tool names include notebook_list, notebook_query, and source_sync_drive.

• Use notebooklm-patterns for RPC-first guidance.

• Override the account used for cookie extraction with GOOGLE_ACCOUNT=your@email.

Recommended Setup (RPC-first)

Use notebooklm-rpc as the default server for full feature parity:

• notebooklm-rpc (expanded toolset, Drive sync, Studio artifacts)

If auth fails, re-run pixi run notebooklm-auth-rpc and retry.

When to Use This Repo vs. jacob-bd Only

You can use jacob-bd/notebooklm-mcp directly if you only need the RPC server tools. This repo adds:

• Codex/Claude CLI wiring (/nlm commands, skills, tool routing).

• Repeatable Pixi tasks for validation and multi-notebook queries.

• Centralized MCP configuration and agent playbooks.

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "notebooklm-rpc": {
      "command": "notebooklm-mcp"
    }
  }
}

Restart Claude Desktop, then:

Add my notebook: https://notebooklm.google.com/notebook/YOUR_ID

Repository Structure

notebooklm-claude-integration/
├── plugins/                         # Claude Code Plugin
│   └── notebooklm/
│       ├── .claude-plugin/
│       │   ├── plugin.json          # Plugin manifest
│       │   └── marketplace.json     # Marketplace manifest
│       ├── commands/
│       │   └── nlm.md               # /nlm command (ask, add, list, select, auth)
│       ├── agents/
│       │   └── research-agent.md    # Proactive research agent
│       ├── skills/
│       │   └── notebooklm-patterns/
│       │       └── SKILL.md         # MCP tools reference & troubleshooting
│       └── README.md
│
├── auth-layer/                      # Multi-backend authentication (NEW)
│   ├── src/
│   │   ├── backends/
│   │   │   ├── cdp.ts               # Chrome DevTools Protocol
│   │   │   ├── keychain.ts          # macOS Keychain storage
│   │   │   └── persistent.ts        # Playwright persistent context
│   │   ├── auth-manager.ts          # Main orchestrator
│   │   ├── cli.ts                   # nlm-auth CLI tool
│   │   └── types.ts                 # TypeScript types
│   ├── package.json
│   └── README.md
│
├── mcp-config/                      # MCP configuration utilities
│   ├── servers.json                 # Unified MCP server config
│   ├── env.example                  # Environment variable template
│   └── README.md                    # Pixi-first install instructions
│
├── docs/                            # Documentation
│   ├── CLAUDE_DESKTOP_SETUP.md
│   ├── CLAUDE_CODE_SETUP.md
│   ├── API_REFERENCE.md
│   └── TROUBLESHOOTING.md
│
├── examples/                        # Usage examples
│
└── tests/                           # Test suite

Codex Skill E2E Test

Use the Pixi task to download the skill from GitHub into a temp repo, load it, and run an end-to-end NotebookLM query through Codex CLI.

Prereqs:

• codex CLI installed

• NotebookLM MCP server added: codex mcp add notebooklm-rpc notebooklm-mcp

• NotebookLM authentication completed at least once

Run:

pixi run codex-skill-e2e

Optional overrides:

NOTEBOOK_URL="https://notebooklm.google.com/notebook/<id>" \
NOTEBOOK_NAME="My Test Notebook" \
NOTEBOOK_DESC="Notebook for testing Codex + NotebookLM." \
NOTEBOOK_ID="my-test-notebook" \
pixi run codex-skill-e2e

Validation checklist (expected results):

• RPC auth is valid (cookies persisted via save_auth_tokens)

• The target notebook exists in notebook_list

• A response is returned with citations

See docs/CODEX_PLAYBOOK.md for a full Codex CLI/SDK validation runbook.

Recommended validation run:

pixi run codex-validate-setup

Codex Improvement Notes

• Use notebook_id for multi-notebook queries to avoid shared state.

• Retry a timed-out notebook_query once, then record a timeout and continue.

Codex Multi-Notebook Query

Run a single question across all notebooks and aggregate results (uses notebook_id to avoid shared state conflicts):

pixi run codex-ask-all

Optional override:

QUESTION="What are the key risks in this architecture?" pixi run codex-ask-all

RPC Auth Refresh

If RPC auth expires, refresh cookies:

pixi run notebooklm-auth-rpc

Pixi RPC Task Runner

All NotebookLM MCP tools are available as pixi run nlm-* tasks (1:1 mapping). See docs/API_REFERENCE.md for the full task list and argument conventions.

Use the notebooklm-rpc server after the file-mode auth:

NOTEBOOK_IDS=pytest-patterns \
QUESTION="Summarize the key sources in this notebook." \
pixi run codex-ask-all-rpc

Filter by notebook IDs (comma-separated):

NOTEBOOK_IDS=pytest-patterns \
QUESTION="Provide modern best practices for integration tests without mocks." \
pixi run codex-ask-all

Validation checklist (expected results):

• Each notebook returns a labeled section

• Citations are included when NotebookLM provides them

• Timeouts are retried once and reported

Repo Hygiene (Pixi-Only)

Install the pre-commit hook to block bash scripts and non-Pixi commands:

pixi run hooks-install

Run locally on demand:

pixi run hooks-run

Codex Multi-Notebook Query (Subagent-aware)

If Codex supports subagents or task parallelism, this script asks a subagent per notebook; otherwise it falls back to sequential queries:

pixi run codex-ask-all-subagents

SDK example:

cd codex-sdk-test
QUESTION="Summarize auth flow changes." npm run test:notebooklm-ask-all

Auth Bootstrap (Recommended for Multi-Process)

Run the auth flow once, then fan out workers that reuse the cookie file:

pixi run notebooklm-auth-rpc

Plugin Commands

Features

Claude Code Plugin

• ✅ /nlm command with subcommands

• ✅ Research agent with automatic follow-up questions

• ✅ Library management (add, list, select, search)

• ✅ Uses existing NotebookLM MCP server

• ✅ Citation-backed answers from Gemini

• ✅ Troubleshooting skill with MCP tools reference

Claude Desktop (MCP)

• ✅ Natural language notebook queries

• ✅ Automatic notebook discovery

• ✅ Citation-backed answers

• ✅ Multi-notebook support

• ✅ Persistent authentication

Architecture

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Claude    │────────>│   Plugin     │────────>│ NotebookLM  │
│  Code CLI   │         │  Commands    │         │ MCP Server  │
└─────────────┘         └──────────────┘         └─────────────┘
                               │                        │
                               │                        v
                               │                 ┌─────────────┐
                               │                 │ Auth Helper │
                               v                 │ (cookies)   │
                        ┌──────────────┐         └─────────────┘
                        │ MCP Tools    │                │
                        │ - notebook_list│              v
                        │ - notebook_query│     ┌─────────────┐
                        │ - notebook_add_url│   │ NotebookLM  │
                        │ - research_start│     │   (Gemini)  │
                        │ - studio_status│      └─────────────┘
                        └──────────────┘

The plugin uses the NotebookLM MCP server which handles:

• Browser automation via Playwright

• Google authentication

• Notebook library management

• Session handling

Use Cases

Quick Research:

/nlm ask "How do I implement OAuth2 in FastAPI?"
# Get instant answer with citations from your docs

Add Documentation:

/nlm source add-url <notebook_id> <url>
# Adds a URL source to a notebook

Deep Research (via agent):

"Research authentication patterns from my documentation"
# research-agent activates, asks follow-up questions, synthesizes answer

Requirements

For Claude Code Plugin:

• Claude Code CLI

• NotebookLM MCP server (notebooklm-mcp-server)

• Google Chrome browser (for auth)

• Google account with NotebookLM access

For Claude Desktop:

• Claude Desktop

• notebooklm-mcp package

Installation Options

Project Scope (Recommended)

claude plugin install notebooklm@notebooklm-plugin --scope project

User Scope (All Projects)

claude plugin install notebooklm@notebooklm-plugin --scope user

Local Scope (Gitignored)

claude plugin install notebooklm@notebooklm-plugin --scope local

Authentication Options

The plugin supports multiple authentication backends (tried in priority order):

RPC Server (Default: File Mode)

For the HTTP/RPC server, default to file-mode auth:

notebooklm-mcp-auth --file

This writes cookies to ~/.notebooklm-mcp/auth.json for RPC use.

Reuse on future runs: if ~/.notebooklm-mcp/auth.json exists, you can skip login.
If auth breaks: re-run notebooklm-mcp-auth --file to refresh cookies.

Validate auth without re-login:

pixi run notebooklm-auth-check-rpc

Recommended: Chrome Remote Debugging (No Popups!)

# 1. Start Chrome with remote debugging
open -a "Google Chrome" --args --remote-debugging-port=9222  # macOS

# 2. Login to NotebookLM in Chrome (one-time)
# Navigate to https://notebooklm.google.com and login with Google

# 3. Now queries use your existing session - no popups!
/nlm ask "How do I implement OAuth?"

Tip: Add to ~/.zshrc or ~/.bashrc:

alias chrome-debug='open -a "Google Chrome" --args --remote-debugging-port=9222'

Troubleshooting

Not Authenticated

# Run notebooklm-mcp-auth and complete login
notebooklm-mcp-auth

# Save RPC auth cookies
/nlm auth rpc

Rate Limited (50 queries/day free tier)

• Wait for daily reset, or

• Re-run notebooklm-mcp-auth with a different Google account

Wrong Notebook

/nlm list           # See all notebooks
# Re-run /nlm ask with the correct notebook_id

See TROUBLESHOOTING.md for complete guide.

Documentation

• Claude Code Setup - Plugin installation guide

• Claude Desktop Setup - MCP setup guide

• API Reference - All commands and options

• Troubleshooting - Common issues and solutions

Security & Privacy

• ✅ All data stored locally by MCP server

• ✅ No data sent to third parties

• ✅ Browser session managed by MCP server

• ✅ Credentials never logged

• ⚠️ Consider dedicated Google account

• ⚠️ NotebookLM terms of service apply

License

MIT License - see LICENSE

Related Projects

• NotebookLM MCP Server - MCP server implementation

• Claude Code - Official Claude Code CLI

• wshobson/agents - Plugin patterns reference

Built with ❤️ for efficient development workflows

Last Updated: December 2024