NotebookLM MCP Server

MCP server for NotebookLM with hybrid metadata enforcement (API-native fields + Google Docs custom properties + local JSON storage).

Features

✅ Metadata Operations: Validate, get, set, and query custom metadata
✅ Notebook Operations: List, get, create, delete, and share notebooks (via NotebookLM API)
✅ Source Operations: Add, get, and remove sources (Google Docs, PDFs, URLs, etc.)
✅ Audio Overviews: Generate and delete audio overviews
✅ Hybrid Storage: Three-layer metadata storage (API fields, Google Docs, local JSON)
✅ OAuth2 Authentication: Secure authentication with auto-refresh
✅ Caching: 30-second TTL for optimal performance
✅ TDD: 89+ tests with comprehensive coverage

Architecture

MCP Server
    ↓
Metadata Manager (Orchestrator)
    ↓ ↓ ↓
[NotebookLM API] [Google Docs API] [Local JSON Store]

Prerequisites

Node.js 18+
Google Cloud Project with:
NotebookLM Enterprise API enabled
Google Docs API enabled
Google Drive API enabled
OAuth2 credentials (client ID and secret)

Installation

# Clone or copy to your machine
cd /path/to/notebooklm-mcp

# Install dependencies
npm install

# Build
npm run build

Configuration

1. Set up OAuth2 Credentials

Set environment variables:

export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"

Or create .env file:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

2. Authenticate (First Time)

Run the setup flow:

npm run setup  # TODO: Implement OAuth web flow in future

This will:

Open your browser to Google OAuth consent screen
Request permissions for NotebookLM, Google Docs, and Drive
Save credentials to ~/.notebooklm-mcp/credentials.json

Manual Testing

Before using the MCP server in production, we recommend following the manual testing guide to verify everything works correctly.

👉 Complete Manual Testing Guide

The guide walks you through:

Phase 1: No-auth metadata validation (5-10 min)
Phase 2: OAuth setup and Claude Code integration (10-15 min)
Phase 3: End-to-end workflow testing (15-20 min)

Quick test (after installation):

# Build the server
npm run build

# Run automated tests
npm test

# Expected: 89 tests passing (10 test suites)

For detailed testing including OAuth and Claude Code integration, see the Manual Testing Guide.

Usage

Start MCP Server

npm start

The server runs on stdio and can be used with Claude Code.

Configure in Claude Code

Add to your Claude Code MCP configuration:

Desktop: ~/.claude/desktop-config.json

{
  "mcpServers": {
    "notebooklm": {
      "command": "/path/to/notebooklm-mcp/bin/notebooklm-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Available MCP Tools

Metadata Operations

notebooklm_validate_metadata - Validate metadata against schema
notebooklm_get_metadata - Get metadata for notebook/source
notebooklm_set_metadata - Set metadata
notebooklm_query_metadata - Query by metadata filter

Notebook Operations

notebooklm_list_notebooks - List recently viewed notebooks
notebooklm_get_notebook - Get notebook details with sources
notebooklm_create_notebook - Create new notebook
notebooklm_delete_notebook - Delete notebook(s)
notebooklm_share_notebook - Share notebook with user

Source Operations

notebooklm_add_sources - Add sources to notebook
notebooklm_get_source - Get source details
notebooklm_remove_sources - Remove sources

Audio Overview Operations

notebooklm_generate_audio - Generate audio overview
notebooklm_delete_audio - Delete audio overview

Metadata Schema (v1.0)

Required Fields

{
  type: "notebook-source"  // Fixed value
  project: string          // Project name
  status: "active" | "archived" | "reference" | "in-progress"
}

Optional Fields

{
  area?: string           // PARA area (e.g., "vocation/spreetail")
  tags?: string[]         // Custom tags
  created?: string        // ISO date (YYYY-MM-DD)
  modified?: string       // ISO date (YYYY-MM-DD)
  customFields?: object   // Extensible custom metadata
}

Example

{
  "type": "notebook-source",
  "project": "palomino-nas",
  "status": "active",
  "area": "vocation/spreetail",
  "tags": ["infrastructure", "backup"],
  "created": "2026-02-17",
  "modified": "2026-02-17",
  "customFields": {
    "priority": "high",
    "owner": "brockbutler"
  }
}

Development

Run Tests

make test
# or
npm test

Watch Mode (TDD)

make test-watch
# or
npm run test:watch

Coverage Report

make test-coverage

Build

make build
# or
npm run build

Project Structure

/Users/brockstudio/Projects/notebooklm-mcp/
├── src/
│   ├── index.ts                    # Entry point
│   ├── server.ts                   # MCP server with 14 tools
│   ├── config.ts                   # Configuration
│   ├── validators/
│   │   └── schema.ts               # Metadata validation
│   ├── storage/
│   │   └── metadata-store.ts       # Local JSON store
│   ├── cache/
│   │   └── manager.ts              # TTL cache
│   ├── auth/
│   │   └── oauth.ts                # OAuth2 manager
│   ├── clients/
│   │   ├── notebooklm.ts          # NotebookLM API client
│   │   └── google-docs.ts         # Google Docs API client
│   └── managers/
│       └── metadata.ts             # Metadata orchestrator
├── tests/
│   ├── unit/                       # Unit tests
│   ├── integration/                # Integration tests
│   └── setup.ts                    # Test setup
├── bin/
│   └── notebooklm-mcp              # Executable wrapper
├── dist/                           # Compiled JavaScript
├── package.json
├── tsconfig.json
├── jest.config.js
├── Makefile
└── README.md

Runtime Files

~/.notebooklm-mcp/
├── credentials.json                # OAuth tokens (chmod 600)
├── metadata.json                   # Local metadata store
└── metadata.json.backup            # Backup (on corruption)

Implementation Status

✅ Completed (Tasks 1-14)

Project scaffold and configuration
Metadata validator with schema enforcement
Local JSON store with atomic writes
Cache manager with TTL
OAuth2 credentials storage and token refresh
Google Docs API client (stub)
NotebookLM API client (stub)
Metadata manager orchestration layer
MCP server with 14 tools
Comprehensive testing (89+ tests)
Integration and end-to-end tests

🔲 Future Enhancements (Post-MVP)

OAuth2 web flow setup wizard
Real Google Docs API integration
Real NotebookLM API integration
Advanced querying (full-text search)
Multi-device metadata sync
Cloud backup for metadata

Troubleshooting

"No credentials found"

Run the setup flow to authenticate with Google:

npm run setup  # TODO: Implement OAuth web flow

"Token refresh failed"

Your refresh token may have expired. Re-run setup:

rm ~/.notebooklm-mcp/credentials.json
npm run setup

"NotebookLM API not yet implemented"

The NotebookLM API operations are currently stubs. They will be implemented in a future phase with real API integration.

Contributing

This project follows TDD principles. All new features require tests.

License

MIT

Design Documents

Architecture: /Users/brockstudio/Projects/palomino-nas/docs/plans/2026-02-16-notebooklm-api-redesign.md
Implementation Plan: /Users/brockstudio/Projects/palomino-nas/docs/plans/2026-02-16-notebooklm-api-implementation.md

notebooklm-mcp