Notebooklm MCP

🚀 NotebookLM MCP

A professional MCP server for Google NotebookLM automation. Available on PyPI and production-ready.

✨ Features

• 🔥 FastMCP v2: A modern decorator-based MCP framework.
• ⚡ UV Python Manager: Lightning-fast dependency management.
• 🚀 Multiple Transports: Supports STDIO, HTTP, and SSE.
• 🎯 Type Safety: Full Pydantic validation.
• 🔒 Persistent Auth: Automatic Google session management.
• 📊 Rich CLI: A beautiful terminal interface with Taskfile automation.
• 🐳 Production Ready: Docker support with monitoring.

🚀 Quick Start

🎯 For End Users (Recommended)

# Install UV (modern Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install NotebookLM MCP from PyPI
uv add notebooklm-mcp

# Initialize with your NotebookLM URL
uv run notebooklm-mcp init https://notebooklm.google.com/notebook/YOUR_NOTEBOOK_ID

What happens after init:

• ✅ Creates notebooklm-config.json with your settings.
• ✅ Creates chrome_profile_notebooklm/ folder for persistent authentication.
• ✅ Opens browser for one-time Google login (if needed).
• ✅ Saves session for future headless operation.

# Start server (STDIO for MCP clients)
uv run notebooklm-mcp --config notebooklm-config.json server

# Start HTTP server for web testing
uv run notebooklm-mcp --config notebooklm-config.json server --transport http --port 8001

# Interactive chat mode
uv run notebooklm-mcp --config notebooklm-config.json chat  --message "Who are you ?"

👨‍💻 For Developers

If you're contributing to this project, check out our Taskfile for an enhanced developer experience:

git clone https://github.com/khengyun/notebooklm-mcp.git
cd notebooklm-mcp

# Complete setup with development tools
task setup

# Show all available development tasks
task --list

📦 Installation

Alternative Installation (pip)

If you prefer pip over UV:

# Install with pip
pip install notebooklm-mcp

# Initialize
notebooklm-mcp init https://notebooklm.google.com/notebook/YOUR_NOTEBOOK_ID

# Start server
notebooklm-mcp --config notebooklm-config.json server

📁 Project Structure After Init

After running init, your working directory will contain:

your-project/
├── notebooklm-config.json          # Configuration file
├── chrome_profile_notebooklm/      # Browser profile (persistent auth)
│   ├── Default/                    # Chrome profile data
│   ├── SingletonSocket             # Session files
│   └── ...                         # Other Chrome data
└── your-other-files

Key files:

• notebooklm-config.json: Contains notebook ID, server settings, auth configuration.
• chrome_profile_notebooklm/: Stores Google authentication session (enables headless operation).

💻 Available Tools

👨‍💻 Developer Workflow

For contributors and advanced users who want enhanced productivity, we provide a comprehensive Taskfile with 20+ automation tasks:

# 📦 Dependency Management
task deps-add -- requests       # Add dependency
task deps-add-dev -- pytest     # Add dev dependency
task deps-remove -- requests    # Remove dependency
task deps-list                  # List dependencies
task deps-update                # Update all dependencies

# 🧪 Testing & Quality
task test                       # Run all tests
task test-quick                 # Quick validation test
task test-coverage              # Coverage analysis
task enforce-test               # MANDATORY after function changes
task lint                       # Run all linting
task format                     # Format code (Black + isort + Ruff)

# 🏗️ Build & Release
task build                      # Build package
task clean                      # Clean artifacts

# 🚀 Server Commands
task server-stdio              # STDIO server
task server-http               # HTTP server
task server-sse                # SSE server

# Show all available tasks
task --list

💡 Usage Tip

Install Task for the best developer experience: go install github.com/go-task/task/v3/cmd/task@latest

🌐 Transport Options

STDIO (Default)

task server-stdio
# For: LangGraph, CrewAI, AutoGen

HTTP

task server-http  
# Access: http://localhost:8001/mcp
# For: Web testing, REST APIs

SSE

task server-sse
# Access: http://localhost:8002/
# For: Real-time streaming

💻 Usage Examples

HTTP Client Testing

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(url="http://localhost:8001/mcp")
async with Client(transport) as client:
    tools = await client.list_tools()
    result = await client.call_tool("healthcheck", {})

Command Line Testing

# Test with curl
curl -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

LangGraph

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

# HTTP transport
transport = StreamableHttpTransport(url="http://localhost:8001/mcp")
client = Client(transport)
tools = await client.list_tools()

CrewAI

from crewai_tools import BaseTool
from fastmcp import Client

class NotebookLMTool(BaseTool):
    name = "notebooklm"
    description = "Chat with NotebookLM"
    
    async def _arun(self, message: str):
        client = Client("http://localhost:8001/mcp")
        result = await client.call_tool("chat_with_notebook", {"message": message})
        return result

🔒 Authentication

Automatic Setup

# First time - opens browser for login
notebooklm-mcp init https://notebooklm.google.com/notebook/abc123

# Subsequent runs - uses saved session
notebooklm-mcp --config notebooklm-config.json server

Manual Setup

# Interactive browser login
notebooklm-mcp --config notebooklm-config.json server

# Check connection
notebooklm-mcp --config notebooklm-config.json test --notebook YOUR_NOTEBOOK_ID

🐳 Docker Deployment

Quick Start

# 1. Generate config + Chrome profile with guided login
uv run notebooklm-mcp init https://notebooklm.google.com/notebook/YOUR_NOTEBOOK_ID
# If you installed via pip, run: notebooklm-mcp init https://notebooklm.google.com/notebook/YOUR_NOTEBOOK_ID

# 2. Build the container image
docker build -t notebooklm-mcp .

# 3. Run the server with your mounted config/profile
docker run -d \
  --name notebooklm-mcp \
  --restart unless-stopped \
  -v $(pwd)/notebooklm-config.json:/app/notebooklm-config.json:ro \
  -v $(pwd)/chrome_profile_notebooklm:/app/chrome_profile_notebooklm \
  notebooklm-mcp:latest

With Compose

version: '3.8'
services:
  notebooklm-mcp:
    image: notebooklm-mcp:latest
    build: .
    restart: unless-stopped
    volumes:
      - ./notebooklm-config.json:/app/notebooklm-config.json:ro
      - ./chrome_profile_notebooklm:/app/chrome_profile_notebooklm

Start the stack with docker compose up -d after running the init command once so that notebooklm-config.json and chrome_profile_notebooklm/ exist. The server runs in STDIO mode by default; uncomment the HTTP/SSE ports in docker-compose.yml if your client requires them.

🔧 Configuration

Config File (notebooklm-config.json)

{
  "default_notebook_id": "your-notebook-id",
  "headless": true,
  "timeout": 30,
  "auth": {
    "profile_dir": "./chrome_profile_notebooklm"
  },
  "debug": false
}

Environment Variables

export NOTEBOOKLM_NOTEBOOK_ID="your-notebook-id"
export NOTEBOOKLM_HEADLESS=true
export NOTEBOOKLM_DEBUG=false

🔧 Technical Details

FastMCP v2 Benefits

• ⚡ 5x faster tool registration with decorators.
• 📋 Auto-generated schemas from Python type hints.
• 🔒 Built-in validation with Pydantic.
• 🧪 Better testing and debugging capabilities.
• 📊 Type safety throughout the stack.

Benchmarks

🛠️ Development

Setup

git clone https://github.com/khengyun/notebooklm-mcp
cd notebooklm-mcp

# With UV (recommended)
uv sync --all-groups

# Or with pip
pip install -e ".[dev]"

Testing

# Run tests with UV
uv run pytest

# With coverage
uv run pytest --cov=notebooklm_mcp

# Integration tests  
uv run pytest tests/test_integration.py

# Or use Taskfile for development
task test
task test-coverage

Code Quality

# Format code with UV
uv run black src/ tests/
uv run ruff check src/ tests/

# Type checking
uv run mypy src/

# Or use Taskfile shortcuts
task format
task lint

📚 Documentation

• Quick Setup Guide - Get started in 2 minutes.
• HTTP Server Guide - Web testing & integration.
• FastMCP v2 Guide - Modern MCP features.
• Docker Deployment - Production setup.
• API Reference - Complete tool documentation.

🔗 Related Projects

• FastMCP - Modern MCP framework.
• MCP Specification - Official MCP spec.
• NotebookLM - Google's AI notebook.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Read the Docs

Built with ❤️ using FastMCP v2 - Modern MCP development made simple!