notebooklm-mcp-cli 0.2.0__tar.gz

notebooklm_mcp_cli-0.2.0/.claude_settings.json

@@ -0,0 +1,34 @@
+{
+  "sandbox": {
+    "enabled": true,
+    "autoAllowBashIfSandboxed": true
+  },
+  "permissions": {
+    "defaultMode": "acceptEdits",
+    "allow": [
+      "Read(./**)",
+      "Write(./**)",
+      "Edit(./**)",
+      "Glob(./**)",
+      "Grep(./**)",
+      "Read(/Users/jbd/dev_projects/notebooklm-mcp/**)",
+      "Write(/Users/jbd/dev_projects/notebooklm-mcp/**)",
+      "Edit(/Users/jbd/dev_projects/notebooklm-mcp/**)",
+      "Glob(/Users/jbd/dev_projects/notebooklm-mcp/**)",
+      "Grep(/Users/jbd/dev_projects/notebooklm-mcp/**)",
+      "Read(/Users/jbd/dev_projects/notebooklm-mcp/.auto-claude/ideation/**)",
+      "Write(/Users/jbd/dev_projects/notebooklm-mcp/.auto-claude/ideation/**)",
+      "Edit(/Users/jbd/dev_projects/notebooklm-mcp/.auto-claude/ideation/**)",
+      "Bash(*)",
+      "WebFetch(*)",
+      "WebSearch(*)",
+      "mcp__context7__resolve-library-id(*)",
+      "mcp__context7__get-library-docs(*)",
+      "mcp__graphiti-memory__search_nodes(*)",
+      "mcp__graphiti-memory__search_facts(*)",
+      "mcp__graphiti-memory__add_episode(*)",
+      "mcp__graphiti-memory__get_episodes(*)",
+      "mcp__graphiti-memory__get_entity_edge(*)"
+    ]
+  }
+}

notebooklm_mcp_cli-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing (OIDC)
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      
+      - name: Set up Python
+        run: uv python install 3.11
+      
+      - name: Build package
+        run: uv build
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

notebooklm_mcp_cli-0.2.0/.gitignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Misc
+.DS_Store
+*.log
+
+# Credentials
+cookies.txt
+
+# uv
+.uv/
+
+# Internal planning docs (do not push)
+Studio_tools_plan.md
+
+# Local project memory (personal, not shared)
+CLAUDE.local.md
+PROJECT_RECAP.md
+todo.md
+.notebooklm*/
+
+
+# Data and Artifacts
+download/
+downloads/
+
+# Auto Claude data directory
+.auto-claude/
+.worktrees/
+.claude/
+run*.notebooklm-py-analysis/
+*.code-workspace

notebooklm_mcp_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.14] - 2026-01-17
+
+### Fixed
+- **Critical Research Stability**:
+  - `poll_research` now accepts status code `6` (Imported) as success, fixing "hanging" Fast Research.
+  - Added `target_task_id` filtering to `poll_research` to ensure the correct research task is returned (essential for Deep Research).
+  - Updated `research_status` and `research_import` to use task ID filtering.
+  - `research_status` tool now accepts an optional `task_id` parameter.
+- **Missing Source Constants**:
+  - Included the code changes for `SOURCE_TYPE_UPLOADED_FILE`, `SOURCE_TYPE_IMAGE`, and `SOURCE_TYPE_WORD_DOC` that were omitted in v0.1.13.
+
+## [0.1.13] - 2026-01-17
+
+### Added
+- **Source type constants** for proper identification of additional source types:
+  - `SOURCE_TYPE_UPLOADED_FILE` (11): Direct file uploads (e.g., .docx uploaded directly)
+  - `SOURCE_TYPE_IMAGE` (13): Image files (GIF, JPEG, PNG)
+  - `SOURCE_TYPE_WORD_DOC` (14): Word documents via Google Drive
+- Updated `SOURCE_TYPES` CodeMapper with `uploaded_file`, `image`, and `word_doc` mappings
+
+## [0.1.12] - 2026-01-16
+
+### Fixed
+- **Standardized source timeouts** (supersedes #9)
+  - Renamed `DRIVE_SOURCE_TIMEOUT` to `SOURCE_ADD_TIMEOUT` (120s)
+  - Applied to all source additions: Drive, URL (websites/YouTube), and Text
+  - Added graceful timeout handling to `add_url_source` and `add_text_source`
+  - Prevents timeout errors when importing large websites or documents
+
+## [0.1.11] - 2026-01-16
+
+### Fixed
+- **Close Chrome after interactive authentication** - Chrome is now properly terminated after `notebooklm-mcp-auth` completes, releasing the profile lock and enabling headless auth for automatic token refresh
+- **Improve token reload from disk** - Removed the 5-minute timeout when reloading tokens during auth recovery. Previously, cached tokens older than 5 minutes were ignored even if the user had just run `notebooklm-mcp-auth`
+
+These fixes resolve "Authentication expired" errors that occurred even after users re-authenticated.
+
+## [0.1.10] - 2026-01-15
+
+### Fixed
+- **Timeout when adding large Drive sources** (fixes #9)
+  - Extended timeout from 30s to 120s for Drive source operations
+  - Large Google Slides (100+ slides) now add successfully
+  - Returns `status: "timeout"` instead of error when timeout occurs, indicating operation may have succeeded
+  - Added `DRIVE_SOURCE_TIMEOUT` constant in `api_client.py`
+
+## [0.1.9] - 2026-01-11
+
+
+### Added
+- **Automatic re-authentication** - Server now survives token expirations without restart
+  - Three-layer recovery: CSRF refresh → disk reload → headless Chrome auth
+  - Works with long-running MCP sessions (e.g., MCP Super Assistant proxy)
+- `refresh_auth` MCP tool for explicit token reload
+- `run_headless_auth()` function for background authentication (if Chrome profile has saved login)
+- `has_chrome_profile()` helper to check if profile exists
+
+### Changed
+- `launch_chrome()` now returns `subprocess.Popen` handle instead of `bool` for cleanup control
+- `_call_rpc()` enhanced with `_deep_retry` parameter for multi-layer auth recovery
+
+## [0.1.8] - 2026-01-10
+
+### Added
+- `constants.py` module as single source of truth for all API code-name mappings
+- `CodeMapper` class with bidirectional lookup (name→code, code→name)
+- Dynamic error messages now show valid options from `CodeMapper`
+
+### Changed
+- **BREAKING:** `quiz_create` now accepts `difficulty: str` ("easy"|"medium"|"hard") instead of `int` (1|2|3)
+- All MCP tools now use `constants.CodeMapper` for input validation
+- All API client output now uses `constants.CodeMapper` for human-readable names
+- Removed ~10 static `_get_*_name` helper methods from `api_client.py`
+- Removed duplicate `*_codes` dictionaries from `server.py` tool functions
+
+### Fixed
+- Removed duplicate code block in research status parsing
+
+## [0.1.7] - 2026-01-10
+
+### Fixed
+- Fixed URL source retrieval by implementing correct metadata parsing in `get_notebook_sources_with_types`
+- Added fallback for finding source type name in `get_notebook_sources_with_types`
+
+## [0.1.6] - 2026-01-10
+
+### Added
+- `studio_status` now includes mind maps alongside audio/video/slides
+- `delete_mind_map()` method with two-step RPC deletion
+- `RPC_DELETE_MIND_MAP` constant for mind map deletion
+- Unit tests for authentication retry logic
+
+### Fixed
+- Mind map deletion now works via `studio_delete` (fixes #7)
+- `notebook_query` now accepts `source_ids` as JSON string for compatibility with some AI clients (fixes #5)
+- Deleted/tombstone mind maps are now filtered from `list_mind_maps` responses
+- Token expiration handling with auto-retry on RPC Error 16 and HTTP 401/403
+
+### Changed
+- Updated `bl` version to `boq_labs-tailwind-frontend_20260108.06_p0`
+- `delete_studio_artifact` now accepts optional `notebook_id` for mind map fallback
+
+## [0.1.5] - 2026-01-09
+
+### Fixed
+- Improved LLM guidance for authentication errors
+
+## [0.1.4] - 2026-01-09
+
+### Added
+- `source_get_content` tool for raw text extraction from sources
+
+## [0.1.3] - 2026-01-08
+
+### Fixed
+- Chrome detection on Linux distros
+
+## [0.1.2] - 2026-01-07
+
+### Fixed
+- YouTube URL handling - use correct array position
+
+## [0.1.1] - 2026-01-06
+
+### Changed
+- Improved research tool descriptions for better AI selection
+
+## [0.1.0] - 2026-01-05
+
+### Added
+- Initial release
+- Full NotebookLM API client with 31 MCP tools
+- Authentication via Chrome DevTools or manual cookie extraction
+- Notebook, source, query, and studio management
+- Research (web/Drive) with source import
+- Audio/Video overview generation
+- Report, flashcard, quiz, infographic, slide deck creation
+- Mind map generation

notebooklm_mcp_cli-0.2.0/CLAUDE.md

@@ -0,0 +1,222 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**NotebookLM MCP Server & CLI** - Provides programmatic access to NotebookLM (notebooklm.google.com) via both a Model Context Protocol server and a comprehensive command-line interface.
+
+Tested with personal/free tier accounts. May work with Google Workspace accounts but has not been tested.
+
+## Development Commands
+
+```bash
+# Install dependencies
+uv tool install .
+
+# Reinstall after code changes (ALWAYS clean cache first)
+uv cache clean && uv tool install --force .
+
+# Run the MCP server (stdio)
+notebooklm-mcp
+
+# Run with Debug logging
+notebooklm-mcp --debug
+
+# Run as HTTP server
+notebooklm-mcp --transport http --port 8000
+
+# Run tests
+uv run pytest
+
+# Run a single test
+uv run pytest tests/test_file.py::test_function -v
+```
+
+**Python requirement:** >=3.11
+
+## Authentication (SIMPLIFIED!)
+
+**You only need to provide COOKIES!** The CSRF token and session ID are now **automatically extracted** when needed.
+
+### Method 1: Chrome DevTools MCP (Recommended)
+
+**Option A - Fast (Recommended):**
+Extract CSRF token and session ID directly from network request - **no page fetch needed!**
+
+```python
+# 1. Navigate to NotebookLM page
+navigate_page(url="https://notebooklm.google.com/")
+
+# 2. Get a batchexecute request (any NotebookLM API call)
+get_network_request(reqid=<any_batchexecute_request>)
+
+# 3. Save with all three fields from the network request:
+save_auth_tokens(
+    cookies=<cookie_header>,
+    request_body=<request_body>,  # Contains CSRF token
+    request_url=<request_url>      # Contains session ID
+)
+```
+
+**Option B - Minimal (slower first call):**
+Save only cookies, tokens extracted from page on first API call
+
+```python
+save_auth_tokens(cookies=<cookie_header>)
+```
+
+### Method 2: Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NOTEBOOKLM_COOKIES` | Yes | Full cookie header from Chrome DevTools |
+| `NOTEBOOKLM_CSRF_TOKEN` | No | (DEPRECATED - auto-extracted) |
+| `NOTEBOOKLM_SESSION_ID` | No | (DEPRECATED - auto-extracted) |
+
+### Token Expiration
+
+- **Cookies**: Stable for weeks, but some rotate on each request
+- **CSRF token**: Auto-refreshed on each client initialization
+- **Session ID**: Auto-refreshed on each client initialization
+
+When API calls fail with auth errors, re-extract fresh cookies from Chrome DevTools.
+
+## Architecture
+
+```
+src/notebooklm_tools/
+├── __init__.py      # Package version
+├── cli/             # CLI commands and formatting
+├── mcp/server.py    # FastMCP server with tool definitions
+├── core/client.py   # Internal API client
+├── core/constants.py # Code-name mappings (CodeMapper class)
+├── core/auth.py     # Token caching and validation
+├── core/auth_cli.py # CLI for Chrome-based auth (notebooklm-mcp-auth)
+└── utils/           # Configuration and browser utilities
+```
+
+**Executables:**
+- `notebooklm-mcp` - The MCP server
+- `notebooklm-mcp-auth` - CLI for extracting tokens (requires closing Chrome)
+
+## MCP Tools Provided
+
+| Tool | Purpose |
+|------|---------|
+| `notebook_list` | List all notebooks |
+| `notebook_create` | Create new notebook |
+| `notebook_get` | Get notebook details |
+| `notebook_describe` | Get AI-generated summary of notebook content with keywords |
+| `source_describe` | Get AI-generated summary and keyword chips for a source |
+| `source_get_content` | Get raw text content from a source (no AI processing) |
+| `notebook_rename` | Rename a notebook |
+| `chat_configure` | Configure chat goal/style and response length |
+| `notebook_delete` | Delete a notebook (REQUIRES confirmation) |
+| `source_add` | Add source (url, text, drive, file) |
+| `notebook_query` | Ask questions (AI answers!) |
+| `source_list_drive` | List sources with types, check Drive freshness |
+| `source_sync_drive` | Sync stale Drive sources (REQUIRES confirmation) |
+| `source_delete` | Delete a source from notebook (REQUIRES confirmation) |
+| `research_start` | Start Web or Drive research to discover sources |
+| `research_status` | Check research progress and get results |
+| `research_import` | Import discovered sources into notebook |
+| `studio_create` | Generate unified content (audio, video, infographic, slides, etc.) |
+| `download_artifact` | Download any artifact (audio, video, pdf, markdown, json) |
+| `export_artifact` | Export Data Tables to Google Sheets or Reports to Google Docs |
+| `studio_status` | Check studio artifact generation status |
+| `studio_delete` | Delete studio artifacts (REQUIRES confirmation) |
+| `notebook_share_status` | Get sharing settings and collaborators |
+| `notebook_share_public` | Enable/disable public link access |
+| `notebook_share_invite` | Invite collaborator by email |
+| `save_auth_tokens` | Save tokens extracted via Chrome DevTools MCP |
+| `refresh_auth` | Reload auth tokens or run headless auth |
+| `note_create` | Create a note in a notebook |
+| `note_list` | List all notes in a notebook |
+| `note_update` | Update a note's content or title |
+| `note_delete` | Delete a note (REQUIRES confirmation) |
+
+**IMPORTANT - Operations Requiring Confirmation:**
+- `notebook_delete` requires `confirm=True` - deletion is IRREVERSIBLE
+- `source_delete` requires `confirm=True` - deletion is IRREVERSIBLE
+- `source_sync_drive` requires `confirm=True` - always show stale sources first via `source_list_drive`
+- All studio creation tools require `confirm=True` - show settings and get user approval first
+- `studio_delete` requires `confirm=True` - list artifacts first via `studio_status`, deletion is IRREVERSIBLE
+- `note_delete` requires `confirm=True` - deletion is IRREVERSIBLE
+
+## Features NOT Yet Implemented
+
+None - all NotebookLM features that can be accessed programmatically are implemented.
+
+## Troubleshooting
+
+### "401 Unauthorized" or "403 Forbidden"
+- Cookies or CSRF token expired
+- Re-extract from Chrome DevTools
+
+### "Invalid CSRF token"
+- The `at=` value expired
+- Must match the current session
+
+### Empty notebook list
+- Session might be for a different Google account
+- Verify you're logged into the correct account
+
+### Rate limit errors
+- Free tier: ~50 queries/day
+- Wait until the next day or upgrade to Plus
+
+## Documentation
+
+### API Reference
+
+**For detailed API documentation** (RPC IDs, parameter structures, response formats), see:
+
+**[docs/API_REFERENCE.md](./docs/API_REFERENCE.md)**
+
+This includes:
+- All discovered RPC endpoints and their parameters
+- Source type structures (URL, text, Drive)
+- Studio content creation (audio, video, reports, etc.)
+- Research workflow details
+- Mind map generation process
+- Source metadata structures
+
+Only read API_REFERENCE.md when:
+- Debugging API issues
+- Adding new features
+- Understanding internal API behavior
+
+### MCP Test Plan
+
+**For comprehensive MCP tool testing**, see:
+
+**[docs/MCP_TEST_PLAN.md](./docs/MCP_TEST_PLAN.md)**
+
+This includes:
+- Step-by-step test cases for all 31 MCP tools
+- Authentication and basic operations tests
+- Source management and Drive sync tests
+- Studio content generation tests (audio, video, infographics, etc.)
+- Quick copy-paste test prompts for validation
+
+Use this test plan when:
+- Validating MCP server functionality after code changes
+- Testing new tool implementations
+- Debugging MCP tool issues
+
+## Contributing
+
+When adding new features:
+
+1. Use Chrome DevTools MCP to capture the network request
+2. Document the RPC ID in docs/API_REFERENCE.md
+3. Add the param structure with comments
+4. Update the api_client.py with the new method
+5. Add corresponding tool in server.py
+6. Update the "Features NOT Yet Implemented" checklist
+7. Add test case to docs/MCP_TEST_PLAN.md
+
+## License
+
+MIT License

notebooklm_mcp_cli-0.2.0/FILE_UPLOAD_IMPLEMENTATION.md

@@ -0,0 +1,93 @@
+# File Upload Implementation
+
+## Overview
+
+File upload uses **HTTP Resumable Upload** – the reliable, headless method.
+
+## HTTP Resumable Upload
+
+### Implementation
+
+Uses Google's 3-step resumable upload protocol:
+
+1. **Register source intent** (RPC: `o4cbdc`) → get SOURCE_ID
+2. **Start upload session** (POST to `/upload/_/`) → get upload URL
+3. **Stream file content** → upload URL (memory-efficient streaming)
+
+### Code Structure
+
+- `SourceMixin._register_file_source()` - Step 1: Register and get SOURCE_ID
+- `SourceMixin._start_resumable_upload()` - Step 2: Get upload URL
+- `SourceMixin._upload_file_streaming()` - Step 3: Stream file content
+- `SourceMixin.add_file()` - Public API that orchestrates all 3 steps
+
+### Usage
+
+**Python:**
+```python
+from notebooklm_tools.core.client import NotebookLMClient
+
+with NotebookLMClient() as client:
+    result = client.add_file(notebook_id="...", file_path="document.pdf")
+# Returns: {"id": "source-id", "title": "document.pdf"}
+```
+
+**CLI:**
+```bash
+nlm source add <notebook-id> --file document.pdf
+```
+
+**MCP:**
+```python
+source_add(notebook_id="...", source_type="file", file_path="/path/to/file.pdf")
+```
+
+### Supported File Types
+
+- PDF (`.pdf`)
+- Text (`.txt`, `.md`)
+- Documents (`.docx`, `.csv`)
+- Audio (`.mp3`)
+- Video (`.mp4`)
+- Images (`.jpg`, `.jpeg`, `.png`)
+
+### Advantages
+
+- ✅ No Chrome dependency
+- ✅ Works in headless/server environments
+- ✅ Memory-efficient streaming for large files
+- ✅ Faster and more reliable
+- ✅ No browser fingerprinting issues
+
+## Testing
+
+```bash
+# Create a test file
+echo "Test content" > test.txt
+
+# Upload the file
+nlm source add <notebook-id> --file test.txt
+
+# Verify it was added
+nlm source list <notebook-id>
+```
+
+## Troubleshooting
+
+### "File not found"
+- **Cause**: The file path doesn't exist or is inaccessible
+- **Fix**: Check the file path spelling and permissions
+
+### "Unsupported file type"
+- **Cause**: File extension is not in the supported list
+- **Fix**: Convert the file to a supported format
+
+### Upload times out
+- **Cause**: Large file or slow connection
+- **Fix**: The upload may still complete on the backend; check notebook sources before retrying
+
+---
+
+## Historical Note
+
+A browser-based upload fallback using Chrome automation was previously available (`--browser` flag) but has been removed. NotebookLM's UI now uses the File System Access API which cannot be automated via CDP. The HTTP method is more reliable anyway.