Skip to main content
Glama

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

Related MCP server: notebooklm-mcp-2026

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:

  1. Open your browser to Google OAuth consent screen

  2. Request permissions for NotebookLM, Google Docs, and Drive

  3. 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

Available Tools

14 tools
notebooklm_add_sourcesB

Add sources to a notebook

Inputs: sources (required), notebookId (required).

notebooklm_create_notebookC

Create a new notebook

Inputs: title (required), description.

notebooklm_delete_audioC

Delete audio overview

Inputs: notebookId (required).

notebooklm_delete_notebookC

Delete notebook(s)

Inputs: notebookIds (required).

notebooklm_generate_audioC

Generate audio overview for a notebook

Inputs: notebookId (required), options.

notebooklm_get_metadataC

Get metadata for a notebook or source

Inputs: id (required), type (required).

notebooklm_get_notebookB

Get notebook details with sources

Inputs: notebookId (required).

notebooklm_get_sourceC

Get source details

Inputs: sourceId (required).

notebooklm_list_notebooksA

List recently viewed notebooks

Inputs: pageSize.

notebooklm_query_metadataC

Query notebooks or sources by metadata

Inputs: type (required), filter (required).

notebooklm_remove_sourcesB

Remove sources from a notebook

Inputs: sourceIds (required).

notebooklm_set_metadataC

Set metadata for a notebook or source

Inputs: id (required), type (required), metadata (required).

notebooklm_share_notebookB

Share notebook with a user

Inputs: role (required), userEmail (required), notebookId (required).

notebooklm_validate_metadataC

Validate metadata against schema

Inputs: metadata (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct resource-action combination: metadata operations are clearly separated into validate/get/set/query, notebook operations into list/get/create/delete/share, and sources/audio each have their own dedicated tools. Even get_notebook and get_source are unambiguous because one returns notebook details with sources and the other returns a specific source's details.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern with the notebooklm_ prefix. Action verbs such as get, set, list, create, delete, add, remove, generate, and share are used predictably across the tool set.

    Tool Count5/5

    14 tools is well within the ideal range for a domain-specific MCP server. The count covers notebooks, sources, metadata, sharing, and audio without feeling bloated or thin.

    Completeness4/5

    The tool surface provides strong lifecycle coverage for notebooks, sources, metadata, and audio overviews. Minor gaps exist such as no explicit notebook update/rename operation, no standalone list-sources tool, and no unshare or list-audio tools, but these are workable gaps rather than critical dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers