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.

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

Command	Description
/nlm ask <question>	Ask a question to a notebook by ID
/nlm list	List all notebooks
/nlm create <name>	Create a new notebook
/nlm auth rpc	Save RPC auth cookies

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):

Backend	Platform	Description
CDP	All	Connect to existing Chrome session (best UX)
Keychain	macOS	Stored cookies in system keychain
Persistent	All	Playwright browser profile
Manual	All	Interactive browser login (fallback)

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