notebooklm-mcp
Allows adding Google Docs as sources to notebooks and reading metadata from Google Docs custom properties.
Allows accessing files from Google Drive for use as sources in notebooks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@notebooklm-mcp List my recent notebooks and sources"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildConfiguration
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-secret2. Authenticate (First Time)
Run the setup flow:
npm run setup # TODO: Implement OAuth web flow in futureThis 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 startThe 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 schemanotebooklm_get_metadata- Get metadata for notebook/sourcenotebooklm_set_metadata- Set metadatanotebooklm_query_metadata- Query by metadata filter
Notebook Operations
notebooklm_list_notebooks- List recently viewed notebooksnotebooklm_get_notebook- Get notebook details with sourcesnotebooklm_create_notebook- Create new notebooknotebooklm_delete_notebook- Delete notebook(s)notebooklm_share_notebook- Share notebook with user
Source Operations
notebooklm_add_sources- Add sources to notebooknotebooklm_get_source- Get source detailsnotebooklm_remove_sources- Remove sources
Audio Overview Operations
notebooklm_generate_audio- Generate audio overviewnotebooklm_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 testWatch Mode (TDD)
make test-watch
# or
npm run test:watchCoverage Report
make test-coverageBuild
make build
# or
npm run buildProject 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.mdRuntime 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.mdImplementation Plan:
/Users/brockstudio/Projects/palomino-nas/docs/plans/2026-02-16-notebooklm-api-implementation.md
Available Tools
14 toolsnotebooklm_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_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
An MCP memory server. One memory your agents share — across models, devices and apps.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceSecure MCP server for querying Google NotebookLM notebooks. Enables AI assistants to list notebooks, read sources, and ask the NotebookLM AI questions about your sources.48 PyPI19MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for querying Google NotebookLM notebooks, enabling AI assistants to list notebooks, read sources, and ask questions about them.MIT
- FlicenseBqualityDmaintenanceA production-ready, fully asynchronous MCP server that bridges AI agents with Google NotebookLM, enabling notebook creation, source management, audio generation, and more through natural language.12-
- AlicenseNot gradedqualityDmaintenanceMCP server that connects AI agents to Google NotebookLM, enabling natural language interaction with notebooks, including Q&A, source ingestion, and audio overview generation.4,646 npmMIT