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. 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.
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

Edit wrangler.jsonc so OAUTH_ISSUER, MCP_RESOURCE, and MCP_AUDIENCE match your deployed Worker URL exactly.

Set secrets through Wrangler stdin only:

openssl rand -base64 48 | wrangler secret put OAUTH_JWT_SIGNING_KEY_B64
openssl rand -base64 32 | wrangler secret put NOTEBOOKLM_CREDENTIAL_ENC_KEY_B64
openssl rand -base64 48 | wrangler secret put CSRF_SIGNING_KEY_B64

Run checks and 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.

MCP Servers