The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
npx ecc-install --profile fullFair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
npx n8nAn open-source AI agent that brings the power of Gemini directly into your terminal.
npx @google/gemini-cli
Programmatic access to Google NotebookLM — via command-line interface (CLI) or Model Context Protocol (MCP) server.
Note: Tested with Pro/free and Google AI Ultra ($249/mo) tier accounts. May work with NotebookLM Enterprise accounts but has not been tested.
📺 Watch the Demos
| Codex Setup + Cinematic Video & Slides |
|---|
 |
| General Overview | Claude Desktop | Perplexity Desktop | MCP Super Assistant |
|---|---|---|---|
 |  |  |  |
| CLI Overview | CLI, MCP & Skills | Setup, Doctor & mcpb | Infographics Support |
|---|---|---|---|
 |  |  |  |
Use nlm directly in your terminal for scripting, automation, or interactive use:
nlm notebook list # List all notebooks
nlm notebook create "Research Project" # Create a notebook
nlm source add <notebook> --url "https://..." # Add sources
nlm audio create <notebook> --confirm # Generate podcast
nlm download audio <notebook> <artifact-id> # Download audio file
nlm share public <notebook> # Enable public link
Run nlm --ai for comprehensive AI-assistant documentation.
Connect AI assistants (Claude, Gemini, Cursor, etc.) to NotebookLM:
# Automatic setup — picks the right config for each tool
nlm setup add claude-code
nlm setup add gemini
nlm setup add github-copilot
nlm setup add cursor
nlm setup add cline
nlm setup add antigravity
# Generate JSON config for any other tool
nlm setup add json
Then use natural language: "Create a notebook about quantum computing and generate a podcast"
| Capability | CLI Command | MCP Tool |
|---|---|---|
| List notebooks | nlm notebook list | notebook_list |
| Create notebook | nlm notebook create | notebook_create |
| Add Sources (URL, Text, Drive, File) | nlm source add | source_add |
| Query notebook (persists to web UI) | nlm notebook query | notebook_query |
| Create Studio Content (Audio, Video, etc.) | nlm studio create | studio_create |
| Revise slide decks | nlm slides revise | studio_revise |
| Download artifacts | nlm download <type> | download_artifact |
| Web/Drive research | nlm research start | research_start |
| Share notebook | nlm share public/invite | notebook_share_* |
📚 More Documentation:
This MCP and CLI use internal APIs that:
Use at your own risk for personal/experimental purposes.
🆕 Claude Desktop users: Download the extension (
.mcpbfile) → double-click → done! One-click install, no config needed.
Install from PyPI. This single package includes both the CLI and MCP server:
uv tool install notebooklm-mcp-cli
uvx --from notebooklm-mcp-cli nlm --help
uvx --from notebooklm-mcp-cli notebooklm-mcp
pip install notebooklm-mcp-cli
pipx install notebooklm-mcp-cli
After installation, you get:
nlm — Command-line interfacenotebooklm-mcp — MCP server for AI assistants# Clone the repository
git clone https://github.com/jacob-bd/notebooklm-mcp-cli.git
cd notebooklm-mcp
# Install with uv
uv tool install .
# Using uv
uv tool upgrade notebooklm-mcp-cli
# Using pip
pip install --upgrade notebooklm-mcp-cli
# Using pipx
pipx upgrade notebooklm-mcp-cli
After upgrading, restart your AI tool to reconnect to the updated MCP server:
/mcp to reconnectIf you previously installed the separate CLI and MCP packages, you need to migrate to the unified package.
uv tool list | grep notebooklm
Legacy packages to remove:
| Package | What it was |
|---|---|
notebooklm-cli | Old CLI-only package |
notebooklm-mcp-server | Old MCP-only package |
# Remove old CLI package (if installed)
uv tool uninstall notebooklm-cli
# Remove old MCP package (if installed)
uv tool uninstall notebooklm-mcp-server
After removing legacy packages, reinstall to fix symlinks:
uv tool install --force notebooklm-mcp-cli
Why
--force? When multiple packages provide the same executable,uvcan leave broken symlinks after uninstalling. The--forceflag ensures clean symlinks.
uv tool list | grep notebooklm
You should see only:
notebooklm-mcp-cli v0.2.0
- nlm
- notebooklm-mcp
Your existing cookies should still work, but if you encounter auth issues:
nlm login
Note: MCP server configuration (in Claude Code, Cursor, etc.) does not need to change — the executable name
notebooklm-mcpis the same.
If you are setting up the tool for the first time — or migrating from a browser-based NotebookLM MCP — see the Getting Started Guide. It covers install, login, agent registration, and a step-by-step migration path that avoids the "two NotebookLM servers registered" trap.
To completely remove the MCP:
# Using uv
uv tool uninstall notebooklm-mcp-cli
# Using pip
pip uninstall notebooklm-mcp-cli
# Using pipx
pipx uninstall notebooklm-mcp-cli
# Remove cached auth tokens and data (optional)
rm -rf ~/.notebooklm-mcp-cli
Also remove from your AI tools:
nlm setup remove claude-code
nlm setup remove cursor
# ... or any configured tool
Before using the CLI or MCP, you need to authenticate with NotebookLM:
# Auto mode: launches your browser, you log in, cookies extracted automatically
nlm login
# Check if already authenticated
nlm login --check
# Use a named profile (for multiple Google accounts)
nlm login --profile work
nlm login --profile personal
# Manual mode: import cookies from a file
nlm login --manual --file cookies.txt
# External CDP provider (e.g., OpenClaw-managed browser)
nlm login --provider openclaw --cdp-url http://127.0.0.1:18800
Profile management:
nlm login --check # Show current auth status
nlm login switch <profile> # Switch the default profile
nlm login profile list # List all profiles with email addresses
nlm login profile delete <profile> # Delete a profile
nlm login profile rename <old> <new> # Rename a profile
Each profile gets its own isolated browser session, so you can be logged into multiple Google accounts simultaneously.
If you only need the MCP server (not the CLI):
nlm login # Auto mode (launches browser)
nlm login --manual # Manual file mode
How it works: Auto mode launches a dedicated browser profile (supports Chrome, Arc, Brave, Edge, Chromium, and more), you log in to Google, and cookies are extracted automatically. Your login persists for future auth refreshes.
Prefer a specific browser? Set it with nlm config set auth.browser chromium (or brave, arc, edge, chrome, etc.). Falls back to auto-detection if the preferred browser is not found.
For detailed instructions and troubleshooting, see docs/AUTHENTICATION.md.
⚠️ Context Window Warning: This MCP provides 39 tools. Disable it when not using NotebookLM to preserve context. In Claude Code:
@notebooklm-mcpto toggle.
Use nlm setup to automatically configure the MCP server for your AI tools — no manual JSON editing required:
# Add to any supported tool
nlm setup add claude-code
nlm setup add claude-desktop
nlm setup add gemini
nlm setup add github-copilot
nlm setup add cursor
nlm setup add windsurf
# Generate JSON config for any other tool
nlm setup add json
# Check which tools are configured
nlm setup list
# Diagnose installation & auth issues
nlm doctor
Install the NotebookLM expert guide for your AI assistant to help it use the tools effectively. Supported for Cline, Antigravity, OpenClaw, Codex, OpenCode, Claude Code, and Gemini CLI.
# Install skill files
nlm skill install cline
nlm skill install openclaw
nlm skill install codex
nlm skill install antigravity
# Update skills
nlm skill update
nlm setup remove claude-code
If you don't want to install the package, you can use uvx to run on-the-fly:
# Run CLI commands directly
uvx --from notebooklm-mcp-cli nlm setup add cursor
uvx --from notebooklm-mcp-cli nlm login
For tools that use JSON config, point them to uvx:
{
"mcpServers": {
"notebooklm-mcp": {
"command": "uvx",
"args": ["--from", "notebooklm-mcp-cli", "notebooklm-mcp"]
}
}
}
Tip: Run
nlm setup add jsonfor an interactive wizard that generates the right JSON snippet for your tool.
Claude Code / Gemini CLI support adding MCP servers via their own CLI:
claude mcp add --scope user notebooklm-mcp notebooklm-mcp
gemini mcp add --scope user notebooklm-mcp notebooklm-mcp
Cursor / Windsurf resolve commands from your PATH, so the command name is enough:
{
"mcpServers": {
"notebooklm-mcp": {
"command": "notebooklm-mcp"
}
}
}
| Tool | Config Location |
|---|---|
| Cursor | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
GitHub Copilot (VS Code workspace) uses .vscode/mcp.json with a top-level servers key:
{
"servers": {
"notebooklm-mcp": {
"command": "notebooklm-mcp",
"args": []
}
}
}
Claude Desktop may not resolve PATH — use the full path to the binary:
{
"mcpServers": {
"notebooklm-mcp": {
"command": "/full/path/to/notebooklm-mcp"
}
}
}
Find your path with: which notebooklm-mcp
| Tool | Config Location |
|---|---|
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json |
| GitHub Copilot | .vscode/mcp.json |
📚 Full configuration details: MCP Guide — Server options, environment variables, HTTP transport, and context window management. For Claude web/mobile and public deployment, read Remote MCP Deployment first.
Simply chat with your AI tool (Claude Code, Cursor, Gemini CLI) using natural language. Here are some examples:
(All queries sent from CLI or MCP automatically persist in your NotebookLM web UI chat history!)
Pro tip: After creating studio content (audio, video, reports, etc.), poll the status to get download URLs when generation completes.
| Component | Duration | Refresh |
|---|---|---|
| Cookies | ~2-4 weeks | Auto-refresh via headless browser (if profile saved) |
| CSRF Token | ~minutes | Auto-refreshed on every request failure |
| Session ID | Per MCP session | Auto-extracted on MCP start |
v0.1.9+: The server now automatically handles token expiration:
You can also call refresh_auth() to explicitly reload tokens.
If automatic refresh fails (Google login fully expired), run nlm login again.
For suspected browser-bound auth replay failures, run nlm doctor auth-replay.
If the cdp_in_page probe succeeds while normal replay fails, see
Experimental browser-backed RPC transport.
uv tool upgrade Not Installing Latest VersionSymptoms:
uv tool upgrade notebooklm-mcp-cli installs an older version (e.g., 0.1.5 instead of 0.1.9)uv cache clean doesn't fix the issueWhy this happens: uv tool upgrade respects version constraints from your original installation. If you initially installed an older version or with a constraint, upgrade stays within those bounds by design.
Fix — Force reinstall:
uv tool install --force notebooklm-mcp-cli
This bypasses any cached constraints and installs the absolute latest version from PyPI.
Verify:
uv tool list | grep notebooklm
# Should show: notebooklm-mcp-cli v0.1.9 (or latest)
See CLAUDE.md for detailed API documentation and how to add new features.
Full transparency: this project was built by a non-developer using AI coding assistants. If you're an experienced Python developer, you might look at this codebase and wince. That's okay.
The goal here was to scratch an itch - programmatic access to NotebookLM - and learn along the way. The code works, but it's likely missing patterns, optimizations, or elegance that only years of experience can provide.
This is where you come in. If you see something that makes you cringe, please consider contributing rather than just closing the tab. This is open source specifically because human expertise is irreplaceable. Whether it's refactoring, better error handling, type hints, or architectural guidance - PRs and issues are welcome.
Think of it as a chance to mentor an AI-assisted developer through code review. We all benefit when experienced developers share their knowledge.
Special thanks to:
source_get_content tool and Linux auth fixes.nlm setup and nlm doctor commands and CLI Guide documentation.| Sync Drive sources |
nlm source sync |
source_sync_drive |
| Batch operations | nlm batch query/create/delete | batch |
| Cross-notebook query | nlm cross query | cross_notebook_query |
| Pipelines (multi-step workflows) | nlm pipeline run/list | pipeline |
| Tag & smart select | nlm tag add/list/select | tag |
| Configure AI tools | nlm setup add/remove/list | — |
| Install AI Skills | nlm skill install/update | — |
| Diagnose issues | nlm doctor | — |
NOTEBOOKLM_HL environment variable (PR #59).cited_text passages in query output (PR #81).AuthHealthChecker that fixes false "stale" reports for semi-stale cookies (PR #219).