Skip to main content
Glama
NotebookLM MCP Gateway

NotebookLM MCP Gateway

NotebookLM MCP 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. OAuth artifacts remain self-contained. Google session cookies are maintained in an encrypted SQLite-backed Durable Object, which serializes rotation, requests, and persistence. Existing KV sessions migrate lazily. Everything runs on Cloudflare Workers; users only need their browser.

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.

Related MCP server: notebooklm-mcp

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 and authoritative Durable Object storage.

  • Domain/path-aware cookies, explicit Google redirects, throttled rotation, and bounded auth recovery ported from notebooklm-py v0.8.5.

  • get_auth_status exposes safe recovery counters and cookie-presence diagnostics without contacting Google.

  • 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:

get_auth_status, 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 tool contracts and docs/AUTHENTICATION.md for the session port, limitations, evidence, and rollout requirements.

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 test:runtime

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:

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

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers