notebooklm-mcp-pro

Production-grade Model Context Protocol server for Google NotebookLM

Connect any MCP-capable client to Google NotebookLM. Works with Claude Desktop, Claude.ai, ChatGPT, Cursor, VS Code Continue, and any client that speaks MCP or OpenAPI.

Documentation · Quick Start · Tools · Integrations

✨ Features

• One Python package.

• One CLI.

• One server factory.

• Local stdio transport.

• Remote Streamable HTTP transport.

• Bearer token authentication.

• GitHub OAuth authentication.

• ChatGPT Custom Actions through OpenAPI 3.1.

• Plugin manifest at /.well-known/ai-plugin.json.

• OAuth metadata endpoints.

• Notebook tools.

• Source ingestion tools.

• Chat tools.

• Research tools.

• Artifact generation tools.

• Artifact lifecycle tools.

• Language tools.

• Admin tools.

• ChatGPT-compatible search.

• ChatGPT-compatible fetch.

• Typed Pydantic inputs.

• Typed output models where the MCP surface needs stable shapes.

• Tool safety annotations.

• Confirmation checks for destructive operations.

• SQLite task tracking.

• SQLite OAuth sessions.

• Structured logging through structlog.

• Offline unit tests.

• Subprocess stdio integration test.

• HTTP auth tests.

• OpenAPI tests.

• Coverage gate.

• Ruff formatting.

• Strict mypy.

• MkDocs Material documentation.

• Docker image.

• Docker Compose template.

• Railway template.

• Fly.io template.

• Kubernetes manifests.

• Release workflow with wheel, sdist, SBOM, PyPI, and GHCR publishing.

Why this exists

Google NotebookLM is useful for research notebooks, source-grounded chat, study material, and artifact generation.

MCP clients need a stable programmatic bridge.

notebooklm-mcp-pro provides that bridge.

It exposes NotebookLM actions as MCP tools.

It exposes NotebookLM records as MCP resources.

It exposes workflow starters as MCP prompts.

It also exposes an OpenAPI action surface for clients that integrate through HTTP schemas.

📦 Installation

uv

uv tool install notebooklm-mcp-pro
nlm-mcp --version

pip

python -m pip install --upgrade notebooklm-mcp-pro
nlm-mcp --version

pipx

pipx install notebooklm-mcp-pro
nlm-mcp --version

Full optional install

python -m pip install "notebooklm-mcp-pro[all]"

From source

git clone https://github.com/oaslananka/notebooklm-mcp-pro
cd notebooklm-mcp-pro
make bootstrap
make test

NotebookLM login

Run the NotebookLM browser login once:

notebooklm-py login

The default auth file is:

~/.config/nlm-mcp/notebooklm_auth.json

Override it with:

export NLM_MCP_NOTEBOOKLM_AUTH_FILE=/secure/path/notebooklm_auth.json

For containers:

export NLM_MCP_NOTEBOOKLM_AUTH_JSON='{"cookies":[],"origins":[]}'

Treat this JSON as a secret.

🚀 Quick Start

Local stdio

pip install notebooklm-mcp-pro
notebooklm-py login
nlm-mcp stdio

Use this mode for local desktop clients.

It does not add an HTTP auth layer.

The caller process controls access.

Remote HTTP with bearer token

export NLM_MCP_TRANSPORT=http
export NLM_MCP_AUTH_MODE=token
export NLM_MCP_BEARER_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export NLM_MCP_BASE_URL=https://your-server.example.com
nlm-mcp serve --host 0.0.0.0 --port 8080

Test:

curl https://your-server.example.com/healthz
curl -H "Authorization: Bearer $NLM_MCP_BEARER_TOKEN" \
  https://your-server.example.com/mcp

Remote HTTP with GitHub OAuth

export NLM_MCP_TRANSPORT=http
export NLM_MCP_AUTH_MODE=github-oauth
export NLM_MCP_BASE_URL=https://your-server.example.com
export NLM_MCP_GITHUB_CLIENT_ID=your-client-id
export NLM_MCP_GITHUB_CLIENT_SECRET=your-client-secret
export NLM_MCP_OAUTH_ALLOWED_USERS=oaslananka
nlm-mcp serve --host 0.0.0.0 --port 8080

Users start at:

https://your-server.example.com/auth/login

🔌 Integrations

Claude Desktop

Add this to the desktop config file.

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Config:

{
  "mcpServers": {
    "notebooklm": {
      "command": "nlm-mcp",
      "args": ["stdio"],
      "env": {
        "NLM_MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

With uvx:

{
  "mcpServers": {
    "notebooklm": {
      "command": "uvx",
      "args": ["notebooklm-mcp-pro", "stdio"]
    }
  }
}

Claude.ai Web

Deploy the HTTP server with a public HTTPS URL.

Use:

https://your-server.example.com/mcp

Choose bearer token or OAuth based on server configuration.

Run admin.health to verify.

ChatGPT Custom Actions

Deploy the HTTP server.

Import:

https://your-server.example.com/openapi.json

Set authentication to bearer token when NLM_MCP_AUTH_MODE=token.

The action endpoints are:

POST /tools/{tool_name}

The manifest is:

GET /.well-known/ai-plugin.json

Cursor

Use the same local stdio config shape:

{
  "mcpServers": {
    "notebooklm": {
      "command": "nlm-mcp",
      "args": ["stdio"]
    }
  }
}

VS Code Continue

Use local stdio or remote HTTP depending on your Continue configuration.

Local command:

nlm-mcp stdio

Remote endpoint:

https://your-server.example.com/mcp

🛠 Tools

Notebook tools

Source tools

Chat tools

Research tools

Generation tools

Artifact lifecycle tools

Language tools

Compatibility tools

Admin tools

⚙️ Configuration

See Configuration for the full table.

🐳 Docker

Build

docker build -f deploy/Dockerfile -t notebooklm-mcp-pro:dev .

Run

docker run --rm -p 8080:8080 \
  -e NLM_MCP_TRANSPORT=http \
  -e NLM_MCP_AUTH_MODE=token \
  -e NLM_MCP_BEARER_TOKEN=replace-with-generated-token \
  -e NLM_MCP_BASE_URL=http://localhost:8080 \
  notebooklm-mcp-pro:dev

Compose

docker compose -f deploy/docker-compose.yml up --build

Pull

docker pull ghcr.io/oaslananka/notebooklm-mcp-pro:latest

HTTP Endpoints

Architecture

flowchart TB
  Desktop["Desktop MCP client"] --> Stdio["stdio transport"]
  Remote["Remote MCP/OpenAPI client"] --> HTTP["Streamable HTTP"]
  HTTP --> Auth["Auth middleware"]
  Stdio --> Server["FastMCP server"]
  Auth --> Server
  Server --> NotebookTools["Notebook tools"]
  Server --> SourceTools["Source tools"]
  Server --> ArtifactTools["Artifact tools"]
  Server --> Resources["MCP resources"]
  Server --> Prompts["MCP prompts"]
  NotebookTools --> Backend["NotebookLMBackend"]
  SourceTools --> Backend
  ArtifactTools --> Backend
  Backend --> NLM["notebooklm-py"]
  NLM --> Google["Google NotebookLM"]
  Server --> Store["SQLite task and OAuth store"]

🔒 Security

• Do not expose HTTP mode publicly without auth.

• Use bearer tokens for personal deployments.

• Use GitHub OAuth for multi-user deployments.

• Store NotebookLM auth JSON in a secret manager.

• Mount auth files read-only in containers.

• Keep NLM_MCP_BASE_URL on HTTPS for OAuth.

• Artifact downloads are constrained to the artifacts directory.

• Destructive tools require explicit confirmation.

• CI runs lint, typecheck, tests, dependency audit, static analysis, and secret scanning.

See Security.

Development

make bootstrap
make lint
make typecheck
make test
make docs

Generate the catalog:

make catalog

Run the HTTP server:

make run-http

Run the stdio server:

make run-stdio

Release

Releases are cut from tags:

git tag v1.0.0
git push origin v1.0.0

The release workflow validates the tag, builds distributions, generates an SBOM, publishes to PyPI, pushes GHCR images, and creates a GitHub release.

Roadmap

Planned follow-up work:

• Additional OAuth providers.

• Shared Redis-backed rate limiting.

• Hosted UI widgets for richer artifact previews.

• More recorded NotebookLM fixtures.

• More deployment blueprints.

See docs/ROADMAP.md.

🤝 Contributing

Contributions are welcome when they are scoped, tested, and documented.

Read CONTRIBUTING.md.

Before opening a PR:

make lint
make typecheck
make test
make docs

Use Conventional Commits.

📄 License

MIT License.

See LICENSE.