# 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 |
| `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) |
| `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
