NotebookLM Gateway

Unofficial TypeScript Cloudflare Worker that exposes a remote Streamable HTTP MCP gateway for NotebookLM.

The gateway lets an MCP client complete OAuth against the Worker, paste a fresh NotebookLM browser request artifact during authorization, and then call NotebookLM through MCP tools. The Worker is intentionally stateless: NotebookLM browser credentials are encrypted into signed OAuth/MCP token artifacts and are not stored in KV, Durable Objects, D1, R2, cache, or the filesystem.

Important disclaimer

This project uses reverse-engineered, undocumented NotebookLM/Google browser APIs.

• It is not affiliated with, endorsed by, or supported by Google, NotebookLM, OpenAI, Anthropic, or Cloudflare.
• NotebookLM internal endpoints, RPC IDs, payload shapes, authentication requirements, quotas, and product behavior may change without notice.
• The MCP tools may break, return partial data, or behave differently across account tiers, regions, languages, and future NotebookLM releases.
• Users paste browser authentication material into the OAuth page. Only self-host this Worker, or use deployments operated by someone you explicitly trust.
• This is best treated as experimental software for personal projects, prototypes, and research automation. There are no stability, availability, or data-loss guarantees.

See SECURITY.md before deploying or connecting real accounts.

Features

• Remote MCP endpoint at /mcp using Streamable HTTP.
• OAuth Authorization Code + PKCE for public clients.
• Dynamic Client Registration at POST /register.
• Short-lived MCP bearer access tokens and stateless refresh tokens bounded by the selected connector expiration.
• Encrypted NotebookLM credential envelopes inside signed OAuth artifacts.
• Supports consumer hosts notebooklm.google.com and notebook.google.com (Gemini Notebook redirect), plus notebooklm.cloud.google.com.
• Server-enforced OAuth/MCP scopes so users can grant read-only or selected chat/write/delete/share capabilities at consent time.
• Zod-backed MCP input/output schemas and structuredContent on successful tool calls.
• Sanitized MCP tool errors and tool outputs that avoid exposing cookies, Authorization headers, JWTs, or raw upstream response bodies.
• Explicit guards for destructive or permission-changing tools.

Tools

The current MCP tool surface covers notebooks, sources, chat, notes, Studio artifacts, research, and sharing:

list_notebooks, get_notebook, create_notebook, rename_notebook, delete_notebook,
list_sources, add_url_source, add_youtube_source, add_text_source, add_drive_source,
get_source_guide, get_source_content, refresh_source, delete_source,
ask_notebook, get_last_conversation_id, get_conversation_turns,
list_notes, create_note, update_note, delete_note,
list_artifacts, generate_artifact, download_artifact,
start_research, poll_research, import_research_sources,
get_share_status, set_share_public

See docs/TOOLS.md for read/write/destructive markers and known limitations.

OAuth and MCP scopes

OAuth consent is least-privilege by default. If the client omits scope or sends it blank, the Worker grants only notebooklm:read. Unknown scopes or duplicate scope parameters are rejected with 400 invalid_request.

Supported scopes:

• notebooklm:read — required baseline; read notebooks, sources, notes, chats, artifacts, and sharing status.
• notebooklm:chat — ask questions, start research, and generate Studio artifacts.
• notebooklm:write — create/edit notebooks, sources, notes, refresh sources, and import research sources.
• notebooklm:delete — delete notebooks, sources, and notes.
• notebooklm:share — change public link sharing.

The authorization page renders human-readable scope checkboxes. Optional scopes requested by the client are pre-checked and can be deselected before granting. Auth codes, access tokens, and refresh tokens carry the granted scope snapshot; refresh-token exchange preserves that exact snapshot and cannot widen access. /token responses include the granted scope string. MCP tools/list only advertises tools allowed by the token scopes, and direct calls to ungranted tools fail without invoking NotebookLM.

Limitations

• NotebookLM APIs are private and can break without warning.
• Browser file upload is not implemented; safe Worker proxying needs additional size, streaming, and trust-boundary work.
• Binary artifact downloads are not proxied. download_artifact requests export metadata/URLs where available.
• Stateless auth codes and refresh tokens cannot be server-side revoked or replay-detected before JWT expiry.
• OAuth/MCP scopes are capability-level only. Object-level authorization still relies on the pasted NotebookLM browser session and upstream NotebookLM permissions.
• Fine-grained user permission management is intentionally limited; only public/private link sharing is exposed through notebooklm:share.

Local development

npm ci
npm run dev
npm test
npm run typecheck

npm run dev uses dummy local-only signing/encryption values and localhost OAuth issuer/resource/audience overrides. Never reuse those values in a deployed Worker.

Deployment overview

Production deploys via GitHub Actions on push to main (or manual workflow_dispatch): test/typecheck, then Cloudflare Workers deploy. Configure a production GitHub Environment with CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Missing Worker secrets are initialized on first deploy; existing secrets are not rotated.

wrangler.jsonc already points OAUTH_ISSUER / MCP_RESOURCE / MCP_AUDIENCE at https://notebooklm-mcp-gateway.xyofn8h7t.workers.dev. Keep those URLs exact after any host change.

Optional local deploy:

npm run check
npx wrangler deploy

Do not store real secrets, browser cookies, Copy-as-cURL artifacts, or MCP/OAuth tokens in .env, .dev.vars, docs, logs, or git.

OAuth redirect policy

Dynamic Client Registration and /authorize enforce a narrow redirect allowlist:

• https://chatgpt.com/connector/oauth/{callback_id} where {callback_id} matches [A-Za-z0-9_-]+
• https://chatgpt.com/connector_platform_oauth_redirect
• https://claude.ai/api/mcp/auth_callback
• loopback http://localhost:{port}/callback, http://127.0.0.1:{port}/callback, and http://[::1]:{port}/callback

Optional OAUTH_EXTRA_REDIRECT_URI_PATTERNS can add tested HTTPS clients. It cannot allow arbitrary non-loopback HTTP redirects.

Credits and prior art

This gateway was built with protocol and UX inspiration from:

• teng-lin/notebooklm-py — comprehensive unofficial NotebookLM Python API/CLI/MCP project.
• jacob-bd/notebooklm-mcp-cli — unofficial NotebookLM CLI and MCP server.

Those projects are independent; credit here does not imply endorsement or shared maintainership.

License

MIT. See LICENSE.