Zotero NotebookLM Plugin

Export research sources from Zotero to NotebookLM with a simple right-click.

This plugin allows you to quickly send URLs from your Zotero library to NotebookLM for AI-powered analysis and research assistance.

Features

• One-Click Export: Right-click on Zotero items and select "Add to NotebookLM"
• Notebook Selection: Choose which NotebookLM notebook to export to
• Batch Export: Export multiple items at once
• Browser Authentication: Secure login via browser-based OAuth flow
• Free NotebookLM Support: Works with consumer/free NotebookLM accounts

Architecture

The plugin uses a hybrid architecture:

• Zotero Plugin (TypeScript): Provides UI and context menu integration
• Python Backend (FastAPI): Handles NotebookLM API communication via notebooklm-py

This design leverages the mature Python ecosystem for NotebookLM integration while maintaining a seamless Zotero user experience.

Prerequisites

• Zotero 8 or higher
• Python 3.10+
• Node.js 18+ (for development only)
• NotebookLM account (free at notebooklm.google.com)

Installation

1. Install Python Dependencies

cd python
uv sync
uv run playwright install chromium

2. Start the Python Server

The server must be running for the plugin to work:

cd python
python -m uvicorn server:app --host 127.0.0.1 --port 5847

Or use the npm script:

npm run start-server

Tip: Keep the server running in a terminal tab while using Zotero.

3. Build the Plugin (For Development)

npm install
npm run build

This compiles TypeScript and creates the plugin files in the build/ directory.

4. Install in Zotero

1. Open Zotero
2. Go to Tools → Plugins
3. Click the gear icon → Install Plugin From File
4. Navigate to the repository and select the built .xpi file (or install from the addon/ directory directly)
5. Restart Zotero

Usage

First Time Setup

1. Authentication: On first use, the plugin will prompt you to login to NotebookLM
2. A browser window will open for you to authenticate with your Google account
3. After authentication, credentials are stored locally for future use

Exporting Items to NotebookLM

1. Select one or more items in your Zotero library that have URLs
2. Right-click and select "Add to NotebookLM"
3. Choose which notebook to export to from the list
4. Wait for the export to complete

The plugin will:

• Extract URLs from the selected items
• Display a notebook selection dialog
• Add each URL to the selected NotebookLM notebook
• Show progress and completion status

Requirements for Items

• Items must have a URL field populated
• Only valid HTTP/HTTPS URLs will be exported
• Invalid URLs will be skipped with a warning

Configuration

Server Port

The default server port is 5847. To change it:

1. Edit python/server.py and change the port in the uvicorn.run() call
2. Update src/modules/notebookmlService.ts to match the new port
3. Rebuild the plugin

Server Auto-Start (Experimental)

The plugin attempts to auto-start the Python server when Zotero launches. If this fails:

1. Start the server manually (see Installation step 2)
2. The plugin will detect the running server automatically

Development

Project Structure

zotero-notebooklm-plugin/
├── src/                    # TypeScript plugin source
│   ├── index.ts            # Main entry point
│   ├── hooks.ts            # Lifecycle management
│   ├── modules/
│   │   ├── contextMenu.ts  # Context menu logic
│   │   ├── notebookmlService.ts  # HTTP client
│   │   └── dialogs.ts      # UI dialogs
│   └── types/
│       └── notebooklm.ts   # TypeScript interfaces
├── python/                 # Python backend
│   ├── server.py           # FastAPI server
│   ├── notebooklm_handler.py  # NotebookLM API wrapper
│   └── auth_manager.py     # Authentication
├── addon/                  # Zotero plugin files
│   ├── manifest.json       # Plugin manifest
│   └── locale/             # Localization
└── build/                  # Compiled output

Building

# Development build with watch
npm run dev

# Production build
npm run build

# Package as XPI
npm run package

Running Tests

# Test Python server
cd python
python -m pytest

# Test server is running
curl http://127.0.0.1:5847/api/health

Troubleshooting

"NotebookLM server not running"

Solution: Start the Python server manually:

cd python
python -m uvicorn server:app --port 5847

"Python dependencies not installed"

Solution: Install required packages:

cd python
uv sync
uv run playwright install chromium

"Login failed"

Solutions:

1. Check your internet connection
2. Ensure you have a NotebookLM account
3. Try logging out and back in
4. Check the Python server logs for errors

"No URLs found"

Solution: Ensure your Zotero items have URLs in the URL field:

1. Select an item in Zotero
2. In the right panel, find the URL field
3. Add the webpage URL for the source

Server Won't Start

Solutions:

1. Check Python is installed: python3 --version
2. Verify uvicorn is installed: python3 -m uvicorn --version
3. Check port 5847 isn't already in use: lsof -i :5847 (macOS/Linux)
4. Review server logs for specific errors

API Endpoints

The Python server provides these endpoints:

• GET /api/health - Health check
• GET /api/auth/status - Check authentication status
• POST /api/auth/login - Trigger login flow
• GET /api/notebooks - List all notebooks
• POST /api/notebooks/{id}/urls - Add URL to notebook
• POST /api/shutdown - Graceful shutdown

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see LICENSE for details

Credits

Built with:

• Zotero 7
• notebooklm-py
• FastAPI
• TypeScript

Support

For issues and feature requests, please use the GitHub issue tracker.