🚀 NotebookLM MCP

Professional MCP server for Google NotebookLM automation • Available on PyPI • Production Ready

Python 3.10+ DeepWiki Tests codecov License: MIT

✨ Key Features

🔥 FastMCP v2: Modern decorator-based MCP framework
⚡ UV Python Manager: Lightning-fast dependency management
🚀 Multiple Transports: STDIO, HTTP, SSE support
🎯 Type Safety: Full Pydantic validation
🔒 Persistent Auth: Automatic Google session management
📊 Rich CLI: 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

✅ 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 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

🔧 Alternative Installation

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

Tool	Description	Parameters
`healthcheck`	Server health status	None
`send_chat_message`	Send message to NotebookLM	`message: str` , `wait_for_response: bool`
`get_chat_response`	Get response with timeout	`timeout: int`
`chat_with_notebook`	Complete interaction	`message: str` , `notebook_id?: str`
`navigate_to_notebook`	Switch notebooks	`notebook_id: str`
`get_default_notebook`	Current notebook	None
`set_default_notebook`	Set default	`notebook_id: str`
`get_quick_response`	Instant response	None

👨‍💻 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

💡 Pro 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

🧪 Testing & Development

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": {}}'

📊 Client Integration

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

🚀 Performance

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

Feature	Traditional MCP	FastMCP v2
Tool registration	Manual schema	Auto-generated
Type validation	Manual	Automatic
Error handling	Basic	Enhanced
Development speed	Standard	5x faster
HTTP support	Limited	Full

🛠️ 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

MIT License - see 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!