notebooklm-mcp-server 0.1.4__tar.gz

notebooklm_mcp_server-0.1.4/.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_server-0.1.4/.gitignore

@@ -0,0 +1,51 @@
+# 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
+
+# uv
+.uv/
+uv.lock
+
+# Internal planning docs (do not push)
+Studio_tools_plan.md
+
+# Local project memory (personal, not shared)
+CLAUDE.local.md

notebooklm_mcp_server-0.1.4/CLAUDE.md

@@ -0,0 +1,214 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**NotebookLM MCP Server** - Provides programmatic access to NotebookLM (notebooklm.google.com) using internal APIs.
+
+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
+notebooklm-mcp
+
+# 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_mcp/
+├── __init__.py      # Package version
+├── server.py        # FastMCP server with tool definitions
+├── api_client.py    # Internal API client
+├── auth.py          # Token caching and validation
+└── auth_cli.py      # CLI for Chrome-based auth (notebooklm-mcp-auth)
+```
+
+**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 |
+| `notebook_rename` | Rename a notebook |
+| `chat_configure` | Configure chat goal/style and response length |
+| `notebook_delete` | Delete a notebook (REQUIRES confirmation) |
+| `notebook_add_url` | Add URL/YouTube source |
+| `notebook_add_text` | Add pasted text source |
+| `notebook_add_drive` | Add Google Drive source |
+| `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 |
+| `audio_overview_create` | Generate audio podcasts (REQUIRES confirmation) |
+| `video_overview_create` | Generate video overviews (REQUIRES confirmation) |
+| `infographic_create` | Generate infographics (REQUIRES confirmation) |
+| `slide_deck_create` | Generate slide decks (REQUIRES confirmation) |
+| `report_create` | Generate reports - Briefing Doc, Study Guide, Blog Post, Custom (REQUIRES confirmation) |
+| `flashcards_create` | Generate flashcards with difficulty options (REQUIRES confirmation) |
+| `quiz_create` | Generate interactive quizzes (REQUIRES confirmation) |
+| `data_table_create` | Generate data tables from sources (REQUIRES confirmation) |
+| `mind_map_create` | Generate and save mind maps (REQUIRES confirmation) |
+| `mind_map_list` | List all mind maps in a notebook |
+| `studio_status` | Check studio artifact generation status |
+| `studio_delete` | Delete studio artifacts (REQUIRES confirmation) |
+| `save_auth_tokens` | Save tokens extracted via Chrome DevTools MCP |
+
+**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
+
+## Features NOT Yet Implemented
+
+- [ ] **Notes** - Save chat responses as notes
+- [ ] **Share notebook** - Collaboration features
+- [ ] **Export** - Download content
+
+## 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_server-0.1.4/GEMINI.md

@@ -0,0 +1,96 @@
+# GEMINI.md
+
+## Project Overview
+
+**NotebookLM MCP Server**
+
+This project implements a Model Context Protocol (MCP) server that provides programmatic access to [NotebookLM](https://notebooklm.google.com). It allows AI agents and developers to interact with NotebookLM notebooks, sources, and query capabilities.
+
+Tested with personal/free tier accounts. May work with Google Workspace accounts but has not been tested. This project relies on internal APIs (`batchexecute` RPCs).
+
+## Environment & Setup
+
+The project uses `uv` for dependency management and tool installation.
+
+### Prerequisites
+- Python 3.11+
+- `uv` (Universal Python Package Manager)
+- Google Chrome (for automated authentication)
+
+### Installation
+
+**From PyPI (Recommended):**
+```bash
+uv tool install notebooklm-mcp-server
+# or: pip install notebooklm-mcp-server
+```
+
+**From Source (Development):**
+```bash
+git clone https://github.com/YOUR_USERNAME/notebooklm-mcp.git
+cd notebooklm-mcp
+uv tool install .
+```
+
+## Authentication (Simplified!)
+
+**You only need to extract cookies** - the CSRF token and session ID are now auto-extracted when the MCP starts.
+
+**Option 1: Chrome DevTools MCP (Recommended)**
+If your AI assistant has Chrome DevTools MCP:
+1. Navigate to `notebooklm.google.com`
+2. Get cookies from any network request
+3. Call `save_auth_tokens(cookies=<cookie_header>)`
+
+**Option 2: Manual (Environment Variables)**
+Extract the `Cookie` header from Chrome DevTools Network tab:
+```bash
+export NOTEBOOKLM_COOKIES="SID=xxx; HSID=xxx; SSID=xxx; ..."
+```
+
+> **Note:** CSRF token and session ID are no longer needed - they are auto-extracted from the page HTML when the MCP initializes.
+
+Cookies last for weeks. When they expire, re-extract fresh cookies.
+
+## Development Workflow
+
+### Building and Running
+
+**Reinstalling after changes:**
+Because `uv tool install` installs into an isolated environment, you must reinstall to see changes during development.
+```bash
+uv cache clean
+uv tool install --force .
+```
+
+**Running the Server:**
+```bash
+notebooklm-mcp
+```
+
+### Testing
+
+Run the test suite using `pytest` via `uv`:
+```bash
+# Run all tests
+uv run pytest
+
+# Run a specific test file
+uv run pytest tests/test_api_client.py
+```
+
+## Project Structure
+
+- `src/notebooklm_mcp/`
+    - `server.py`: Main entry point. Defines the MCP server and tools.
+    - `api_client.py`: The core logic. Contains the internal API calls.
+    - `auth.py`: Handles token validation, storage, and loading.
+    - `auth_cli.py`: Implementation of the `notebooklm-mcp-auth` CLI.
+- `CLAUDE.md`: Contains detailed documentation on the internal RPC IDs and protocol specifics. **Refer to this file for API deep dives.**
+- `pyproject.toml`: Project configuration and dependencies.
+
+## Key Conventions
+
+- **Internal APIs:** This project relies on undocumented APIs. Changes to Google's internal API will break functionality.
+- **RPC Protocol:** The API uses Google's `batchexecute` protocol. Responses often contain "anti-XSSI" prefixes (`)]}'`) that must be stripped.
+- **Tools:** New features should be exposed as MCP tools in `server.py`.

notebooklm_mcp_server-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jacob Ben David
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.