Skip to content
Back to search

gemini-notebook-mcp-cli

Programmatic access to Gemini Notebook - via command-line interface (CLI), Model Context Protocol (MCP) server, and AI agent skills.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jacob-bd/gemini-notebook-mcp-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jacob-bd/gemini-notebook-mcp-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jacob-bd--gemini-notebook-mcp-cli/badge.svg)](/listings/jacob-bd--gemini-notebook-mcp-cli)

HTML

<a href="/listings/jacob-bd--gemini-notebook-mcp-cli"><img src="/api/listings/jacob-bd--gemini-notebook-mcp-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Three commands take you from nothing to a connected AI assistant:

1. Install (gives you `nlm` and the MCP server):

uv tool install notebooklm-mcp-cli

2. Sign in to your Google account:

nlm login

3. Connect your AI tools:

nlm setup

The setup wizard (`nlm setup`)

`nlm setup` finds the AI tools installed on your machine and connects them to Gemini Notebook — no config files to edit. Pick an option with the arrow keys:

| Menu option | What it does | |---|---| | **Show my tools' status** | One table for every detected tool: MCP connection (✓ set up · ✗ not yet · ⚠ old name) and skill version (⬆ when an upgrade is available). | | **Add the MCP to my tools/agents** | Tick the tools to connect (Space), then Enter. Nothing is pre-selected. Connections still using the old `notebooklm-mcp` name appear under **Needs a fix** and are renamed to `gemini-notebook-mcp`, keeping their settings. Then it offers the skill. | | **Add the skill to my tools/agents** | Installs the skill that teaches your AI how to use Gemini Notebook well — for **All my projects** (default) or **Just this folder**. Upgrades are pre-ticked; older versions are only replaced after you confirm. | | **Remove an MCP or skill** | Lists what's installed, grouped into MCP connections and skills. Nothing is pre-selected, and each group needs its own confirmation. | | **Credential protection** | Protect your saved logins in your OS keystore, or restore them to plain files. It only offers what applies: *Protect* when a login is plain, *Restore* when one is protected. With several logins you get a checkbox picker. | | **Copy MCP setup for a tool not listed** | Copies a ready-to-paste JSON snippet to your clipboard. **Advanced options** switch to uvx, the bare command, or entry-only JSON. |

- **Esc** goes back from any screen (and quits from the main menu). - Every file is **backed up** to `~/.notebooklm-mcp-cli/backups/` before it is changed. - **Connects to:** Claude Code, Claude Desktop (regular and Relay AI / 3P), Codex CLI / ChatGPT desktop app, Gemini CLI, Cursor, Windsurf, Cline, Antigravity, GitHub Copilot (VS Code), and OpenCode. The skill also installs for Hermes and OpenClaw. - **Claude Desktop Chat & Cowork, and claude.ai:** these only use skills uploaded to your Claude account. In **Add the skill**, tick **Claude Desktop / claude.ai** — the wizard saves `~/Downloads/nlm-skill.zip` and shows where to upload it (**Customize → Skills → Add**). Or run `nlm skill package`. - **Claude Desktop:** fully quit it (Cmd+Q) before connecting — it can overwrite its settings while open, so the wizard refuses to write until it's closed. - **Scripts and CI:** every option has a direct command — `nlm setup add <tool>`, `nlm setup remove <tool>`, `nlm setup list`, `nlm skill install <tool>`. See [MCP Configuration](#mcp-configuration).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 800 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Gemini Notebook (formerly Google NotebookLM) CLI & MCP Server
  2. ![Gemini Notebook MCP Header](docs/media/header.jpg)
  3. [![PyPI version](https://img.shields.io/pypi/v/notebooklm-mcp-cli)](https://pypi.org/project/notebooklm-mcp-cli/)
  4. [![PyPI downloads](https://img.shields.io/pypi/dm/notebooklm-mcp-cli)](https://pypistats.org/packages/notebooklm-mcp-cli)
  5. [![Total downloads](https://static.pepy.tech/badge/notebooklm-mcp-cli)](https://pepy.tech/projects/notebooklm-mcp-cli)
  6. [![Python](https://img.shields.io/pypi/pyversions/notebooklm-mcp-cli)](https://pypi.org/project/notebooklm-mcp-cli/)
  7. [![License](https://img.shields.io/pypi/l/notebooklm-mcp-cli)](https://github.com/jacob-bd/gemini-notebook-mcp-cli/blob/main/LICENSE)
  8. **Programmatic access to Gemini Notebook** — via command-line interface (CLI) or Model Context Protocol (MCP) server.
  9. > 🚨 **New: Protected login storage (recommended)**
  10. > Your saved Google login can now be encrypted, with its key kept in your computer's keychain instead of a plain file. We highly recommend everyone switch on a personal computer:
  11. >
  12. > nlm auth storage set protected
  13. >
  14. > 💡 You can also use the 'nlm setup' wizard and select the 'Credentials Protection' option in the wizard
  15. >
  16. > Optional: nothing changes unless you turn it on. Servers, cron, Docker and SSH setups can keep the plain file.
  17. > 📖 [How it works](docs/AUTHENTICATION.md#protected-storage) · 📺 [Watch this short video](https://www.youtube.com/shorts/7ZmF_lwJh3M)
  18. >
  19. > 🤖 Fun fact: this video was created by an agent using the gemini-notebook-mcp.
  20. > **Note:** Personal/consumer accounts are tested regularly. Gemini Notebook Enterprise support is experimental. The documented `notebook.cloud.google.com` host has been live-verified with a project-qualified `global` deployment; other Enterprise host variants may require additional validation.
  21. > ☕ **If you find notebooklm-mcp-cli useful, consider [buying me a coffee](https://buymeacoffee.com/jacobbd).**
  22. > It's free and built in my spare time — but testing every Gemini Notebook feature takes real time and resources. A coffee helps me cover it and keep shipping. Thank you! 🙏
  23. >
  24. > <a href="https://buymeacoffee.com/jacobbd"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="42"></a>
  25. ## 📺 Watch the demos
  26. Real workflows, start to finish. The newest videos are first, then the demo that matches how you work.
  27. > **New here?** Start with **[Claude in 5 minutes](https://www.youtube.com/watch?v=PU8JhgLPxes)**. It is the shortest path from install to your first notebook query.
  28. ### Set up and connect
  29. | **Claude Cowork & Interactive Reports** | **Setup** | **Local AI** | **Any AI client** |
  30. | :---: | :---: | :---: | :---: |
  31. | [![Claude takes over Gemini Notebook](https://img.youtube.com/vi/UXxqTpNNGt0/mqdefault.jpg)](https://www.youtube.com/watch?v=UXxqTpNNGt0)<br>**Watch Claude take over**<br><sub>The full build, start to finish<br>22 min</sub> | [![Set up the MCP server](https://img.youtube.com/vi/5tOUilBTJ3Q/mqdefault.jpg)](https://www.youtube.com/watch?v=5tOUilBTJ3Q)<br>**Set up the server**<br><sub>Wizard, doctor, and mcpb<br>16 min</sub> | [![Use LM Studio with your notebook](https://img.youtube.com/vi/OmtvmPBQzkM/mqdefault.jpg)](https://www.youtube.com/watch?v=OmtvmPBQzkM)<br>**Use LM Studio locally**<br><sub>A local model, same notebook<br>8 min</sub> | [![ChatGPT, Grok, Gemini and more](https://img.youtube.com/vi/7aHDbkr-l_E/mqdefault.jpg)](https://www.youtube.com/watch?v=7aHDbkr-l_E)<br>**ChatGPT, Grok, Gemini and more**<br><sub>One server, many front ends<br>15 min</sub> |
  32. ### Create and automate
  33. | **Codex setup, cinematic video & slides** | **Studio video** | **Infographics** | **CLI** |
  34. | :---: | :---: | :---: | :---: |
  35. | [![Turn code into a cinematic video](https://img.youtube.com/vi/KrgLCrvU1dw/mqdefault.jpg?v=20261002)](https://www.youtube.com/watch?v=KrgLCrvU1dw)<br>**Turn code into a cinematic video**<br><sub>Codex and NotebookLM, end to end<br>14 min</sub> | [![See the cinematic result](https://img.youtube.com/vi/iu4L6H6gMD8/mqdefault.jpg)](https://www.youtube.com/watch?v=iu4L6H6gMD8)<br>**See the cinematic result**<br><sub>A two-minute taste of the workflow<br>2 min</sub> | [![Try all 10 infographic styles](https://img.youtube.com/vi/Uc6iH5NuQ9A/mqdefault.jpg)](https://www.youtube.com/watch?v=Uc6iH5NuQ9A)<br>**Try all 10 infographic styles**<br><sub>Every style, side by side<br>11 min</sub> | [![Automate research in your terminal](https://img.youtube.com/vi/XyXVuALWZkE/mqdefault.jpg)](https://www.youtube.com/watch?v=XyXVuALWZkE)<br>**Automate research in your terminal**<br><sub>Create, query, and download from the CLI<br>13 min</sub> |
  36. ### More demos
  37. | **Perplexity** | **How it works** | **Overview** |
  38. | :---: | :---: | :---: |
  39. | [![Connect Perplexity to NotebookLM](https://img.youtube.com/vi/BCKlDNg-qxs/mqdefault.jpg)](https://www.youtube.com/watch?v=BCKlDNg-qxs)<br>**Connect Perplexity to NotebookLM**<br><sub>See what happens with MCP access<br>10 min</sub> | [![NotebookLM has no API. So I built one.](https://img.youtube.com/vi/ZQBQigFK-E8/mqdefault.jpg)](https://www.youtube.com/watch?v=ZQBQigFK-E8)<br>**NotebookLM has no API. So I built one.**<br><sub>The story behind the CLI and server<br>12 min</sub> | [![Automate research and content creation](https://img.youtube.com/vi/d-PZDQlO4m4/mqdefault.jpg)](https://www.youtube.com/watch?v=d-PZDQlO4m4)<br>**Automate research and content creation**<br><sub>The original end-to-end overview<br>16 min</sub> |
  40. ## ⚡ Quick Start
  41. Three commands take you from nothing to a connected AI assistant:
  42. 1. Install (gives you `nlm` and the MCP server):
  43. ```bash
  44. uv tool install notebooklm-mcp-cli
  45. ```
  46. 2. Sign in to your Google account:
  47. ```bash
  48. nlm login
  49. ```
  50. 3. Connect your AI tools:
  51. ```bash
  52. nlm setup
  53. ```
  54. ### The setup wizard (`nlm setup`)
  55. `nlm setup` finds the AI tools installed on your machine and connects them to
  56. Gemini Notebook — no config files to edit. Pick an option with the arrow keys:
  57. | Menu option | What it does |
  58. |---|---|
  59. | **Show my tools' status** | One table for every detected tool: MCP connection (✓ set up · ✗ not yet · ⚠ old name) and skill version (⬆ when an upgrade is available). |
  60. | **Add the MCP to my tools/agents** | Tick the tools to connect (Space), then Enter. Nothing is pre-selected. Connections still using the old `notebooklm-mcp` name appear under **Needs a fix** and are renamed to `gemini-notebook-mcp`, keeping their settings. Then it offers the skill. |
  61. | **Add the skill to my tools/agents** | Installs the skill that teaches your AI how to use Gemini Notebook well — for **All my projects** (default) or **Just this folder**. Upgrades are pre-ticked; older versions are only replaced after you confirm. |
  62. | **Remove an MCP or skill** | Lists what's installed, grouped into MCP connections and skills. Nothing is pre-selected, and each group needs its own confirmation. |
  63. | **Credential protection** | Protect your saved logins in your OS keystore, or restore them to plain files. It only offers what applies: *Protect* when a login is plain, *Restore* when one is protected. With several logins you get a checkbox picker. |
  64. | **Copy MCP setup for a tool not listed** | Copies a ready-to-paste JSON snippet to your clipboard. **Advanced options** switch to uvx, the bare command, or entry-only JSON. |
  65. - **Esc** goes back from any screen (and quits from the main menu).
  66. - Every file is **backed up** to `~/.notebooklm-mcp-cli/backups/` before it is changed.
  67. - **Connects to:** Claude Code, Claude Desktop (regular and Relay AI / 3P), Codex CLI / ChatGPT desktop app, Gemini CLI, Cursor, Windsurf, Cline, Antigravity, GitHub Copilot (VS Code), and OpenCode. The skill also installs for Hermes and OpenClaw.
  68. - **Claude Desktop Chat & Cowork, and claude.ai:** these only use skills uploaded to your Claude account. In **Add the skill**, tick **Claude Desktop / claude.ai** — the wizard saves `~/Downloads/nlm-skill.zip` and shows where to upload it (**Customize → Skills → Add**). Or run `nlm skill package`.
  69. - **Claude Desktop:** fully quit it (Cmd+Q) before connecting — it can overwrite its settings while open, so the wizard refuses to write until it's closed.
  70. - **Scripts and CI:** every option has a direct command — `nlm setup add <tool>`, `nlm setup remove <tool>`, `nlm setup list`, `nlm skill install <tool>`. See [MCP Configuration](#mcp-configuration).
  71. ## Two Ways to Use
  72. ### 🖥️ Command-Line Interface (CLI)
  73. Use `nlm` directly in your terminal for scripting, automation, or interactive use:
  74. ```bash
  75. nlm notebook list # List all notebooks
  76. nlm notebook create "Research Project" # Create a notebook
  77. nlm source add <notebook> --url "https://..." # Add sources
  78. nlm audio create <notebook> --confirm # Generate podcast
  79. nlm download audio <notebook> --id <artifact-id> # Download audio file
  80. nlm download all <notebook> -d ./exports # Download every artifact
  81. nlm share public <notebook> # Enable public link
  82. ```
  83. Run `nlm --ai` for comprehensive AI-assistant documentation.
  84. ### 🤖 MCP Server (for AI Agents)
  85. Connect AI assistants (Claude, Gemini, Cursor, etc.) to Gemini Notebook:
  86. ```bash
  87. nlm setup # Guided wizard — see Quick Start above
  88. nlm setup add codex # Or connect one client directly
  89. ```
  90. Then use natural language: _"Create a notebook about quantum computing and generate a podcast"_
  91. ## Features
  92. | Capability | CLI Command | MCP Tool |
  93. | --------------------------------------------- | ------------------------------- | ------------------------------------ |
  94. | List notebooks | `nlm notebook list` | `notebook_list` |
  95. | Create notebook | `nlm notebook create` | `notebook_create` |
  96. | Add Sources (URL, Text, Drive, File) | `nlm source add` | `source_add` |
  97. | Query notebook (persists to web UI) | `nlm notebook query` | `notebook_query` |
  98. | List/view/export/delete chat sessions | `nlm chats list/get/export/delete` | `chat_list`/`chat_get`/`chat_export`/`chat_delete` |
  99. | Create Studio Content (Audio, Video, etc.) | `nlm studio create` | `studio_create` |
  100. | Interactive reports (read + embedded elements)| `nlm report get/elements/element` | `report` (action=get/elements/generate) |
  101. | Revise slide decks | `nlm slides revise` | `studio_revise` |
  102. | Download artifacts | `nlm download <type>` | `download_artifact` |
  103. | Download all artifacts (one or all notebooks) | `nlm download all` | `download_all_artifacts` |
  104. | Web/Drive research | `nlm research start` | `research_start` |
  105. | Share notebook | `nlm share public/invite` | `notebook_share_*` |
  106. | Sync Drive sources | `nlm source sync` | `source_sync_drive` |
  107. | Batch operations | `nlm batch query/create/delete` | `batch` |
  108. | Cross-notebook query | `nlm cross query` | `cross_notebook_query` |
  109. | Pipelines (multi-step workflows) | `nlm pipeline run/list` | `pipeline` |
  110. | Tag & smart select | `nlm tag add/list/select` | `tag` |
  111. | Manage collections (home page groups) | — | `collection_*` |
  112. | Configure AI tools | `nlm setup` (wizard), `nlm setup add/remove/list` | — |
  113. | Install AI Skills | `nlm skill install/update` | — |
  114. | Diagnose issues | `nlm doctor` | — |
  115. | Check remaining plan usage | `nlm usage [--profile <name>]` | `usage_get` |
  116. | Manage login encryption (Protected mode) | `nlm auth storage status/set` | — |
  117. 📚 **More Documentation:**
  118. - **[Getting Started](docs/GETTING_STARTED.md)** — Install, login, agent setup, and migration from another Gemini Notebook MCP
  119. - **[CLI Guide](docs/CLI_GUIDE.md)** — Complete command reference
  120. - **[MCP Guide](docs/MCP_GUIDE.md)** — All 55 MCP tools with examples
  121. - **[Authentication](docs/AUTHENTICATION.md)** — Setup and troubleshooting
  122. - **[Remote MCP](docs/REMOTE_MCP.md)** — Web/mobile connector feasibility, security, and authentication limitations
  123. - **[API Reference](docs/API_REFERENCE.md)** — Internal API docs for contributors
  124. ## Important Disclaimer
  125. This MCP and CLI use **internal APIs** that:
  126. - Are undocumented and may change without notice
  127. - Require cookie extraction from your browser (I have a tool for that!)
  128. - May not be aligned with Google's Terms of Service
  129. Use at your own risk for personal/experimental purposes.
  130. ## Installation
  131. > 🆕 **Claude Desktop users:** [Download the extension](https://github.com/jacob-bd/gemini-notebook-mcp-cli/releases/latest) (`.mcpb` file) → double-click → done! One-click install, no config needed.
  132. Install from PyPI. This single package includes **both the CLI and MCP server**:
  133. ### Using uv (Recommended)
  134. ```bash
  135. uv tool install notebooklm-mcp-cli
  136. ```
  137. ### Using uvx (Run Without Install)
  138. ```bash
  139. uvx --from notebooklm-mcp-cli nlm --help
  140. uvx --from notebooklm-mcp-cli notebooklm-mcp
  141. ```
  142. ### Using pip
  143. ```bash
  144. pip install notebooklm-mcp-cli
  145. ```
  146. ### Using pipx
  147. ```bash
  148. pipx install notebooklm-mcp-cli
  149. ```
  150. **After installation, you get:**
  151. - `nlm` — Command-line interface
  152. - `notebooklm-mcp` — Gemini Notebook MCP server for AI assistants
  153. <details>
  154. <summary>Alternative: Install from Source</summary>
  155. ```bash
  156. # Clone the repository
  157. git clone https://github.com/jacob-bd/gemini-notebook-mcp-cli.git
  158. cd notebooklm-mcp
  159. # Install with uv
  160. uv tool install .
  161. ```
  162. </details>
  163. ## Upgrading
  164. ```bash
  165. # Using uv
  166. uv tool upgrade notebooklm-mcp-cli
  167. # Using pip
  168. pip install --upgrade notebooklm-mcp-cli
  169. # Using pipx
  170. pipx upgrade notebooklm-mcp-cli
  171. ```
  172. After upgrading, restart your AI tool to reconnect to the updated MCP server:
  173. - **Claude Code:** Restart the application, or use `/mcp` to reconnect
  174. - **Cursor:** Restart the application
  175. - **Gemini CLI:** Restart the CLI session
  176. ## Upgrading from Legacy Versions
  177. If you previously installed the **separate** CLI and MCP packages, you need to migrate to the unified package.
  178. ### Step 1: Check What You Have Installed
  179. ```bash
  180. uv tool list | grep notebooklm
  181. ```
  182. **Legacy packages to remove:**
  183. | Package | What it was |
  184. |---------|-------------|
  185. | `notebooklm-cli` | Old CLI-only package |
  186. | `notebooklm-mcp-server` | Old MCP-only package |
  187. ### Step 2: Uninstall Legacy Packages
  188. ```bash
  189. # Remove old CLI package (if installed)
  190. uv tool uninstall notebooklm-cli
  191. # Remove old MCP package (if installed)
  192. uv tool uninstall notebooklm-mcp-server
  193. ```
  194. ### Step 3: Reinstall the Unified Package
  195. After removing legacy packages, reinstall to fix symlinks:
  196. ```bash
  197. uv tool install --force notebooklm-mcp-cli
  198. ```
  199. > **Why `--force`?** When multiple packages provide the same executable, `uv` can leave broken symlinks after uninstalling. The `--force` flag ensures clean symlinks.
  200. ### Step 4: Verify Installation
  201. ```bash
  202. uv tool list | grep notebooklm
  203. ```
  204. You should see only:
  205. ```
  206. notebooklm-mcp-cli v0.2.0
  207. - nlm
  208. - notebooklm-mcp
  209. ```
  210. ### Step 5: Re-authenticate
  211. Your existing cookies should still work, but if you encounter auth issues:
  212. ```bash
  213. nlm login
  214. ```
  215. > **Note:** The configured MCP server name is now `gemini-notebook-mcp`. The executable remains `notebooklm-mcp` for compatibility with existing installations.
  216. ## Getting Started
  217. If you are setting up the tool for the first time — or migrating from a
  218. browser-based Gemini Notebook MCP — see the
  219. [Getting Started Guide](docs/GETTING_STARTED.md). It covers install,
  220. login, agent registration, and a step-by-step migration path that avoids
  221. the "two Gemini Notebook servers registered" trap.
  222. ## Uninstalling
  223. To completely remove the MCP:
  224. ```bash
  225. # Using uv
  226. uv tool uninstall notebooklm-mcp-cli
  227. # Using pip
  228. pip uninstall notebooklm-mcp-cli
  229. # Using pipx
  230. pipx uninstall notebooklm-mcp-cli
  231. # Remove cached auth tokens and data (optional)
  232. rm -rf ~/.notebooklm-mcp-cli
  233. ```
  234. Also remove from your AI tools:
  235. ```bash
  236. nlm setup remove claude-code
  237. nlm setup remove cursor
  238. # ... or any configured tool
  239. ```
  240. ## Authentication
  241. Before using the CLI or MCP, you need to authenticate with Gemini Notebook:
  242. ### CLI Authentication (Recommended)
  243. ```bash
  244. # Auto mode: launches your browser, you log in, cookies extracted automatically
  245. nlm login
  246. # Check if already authenticated
  247. nlm login --check
  248. # Use a named profile (for multiple Google accounts)
  249. nlm login --profile work
  250. nlm login --profile personal
  251. # Manual mode: import cookies from a file
  252. nlm login --manual --file cookies.txt
  253. # External CDP provider (e.g., OpenClaw-managed browser)
  254. nlm login --provider openclaw --cdp-url http://127.0.0.1:18800
  255. ```
  256. New profiles ask where to keep the saved login **before** the browser opens: **Protected** (encrypted, key in your OS keystore, recommended) or a plain file. Scripts can skip the question with `nlm login --storage protected` (or `--storage file`). Existing profiles keep their mode; change it any time in `nlm setup` → **Credential protection**.
  257. **Profile management:**
  258. ```bash
  259. nlm login --check # Show current auth status
  260. nlm login switch <profile> # Switch the default profile
  261. nlm login profile list # List all profiles with email addresses
  262. nlm login profile delete <profile> # Delete a profile
  263. nlm login profile rename <old> <new> # Rename a profile
  264. ```
  265. **From an MCP-only app (for example Claude CoWork):** ask the AI to use the `profile` tool. It can list your accounts, switch for the session, and, only if you ask, make one your saved default.
  266. **Unattended / scheduled refresh:**
  267. A live session self-heals — when Google's short-lived cookies age out, the
  268. client automatically runs a headless refresh. For unattended machines you can
  269. also refresh proactively from a scheduler so a session never lapses:
  270. ```bash
  271. nlm auth refresh # Headless, no interaction; exits non-zero on failure
  272. nlm auth refresh --profile work # Refresh a named profile
  273. nlm auth refresh --http-only # Validate without opening a browser
  274. ```
  275. `--http-only` forces HTTP transport, including when CDP transport is configured.
  276. It cannot renew browser-dependent PSIDTS cookies or revive a fully expired login.
  277. Automatic recovery uses a per-process cooldown and failure budget; explicit
  278. refresh commands bypass these limits. See [authentication guidance](docs/AUTHENTICATION.md#automatic-recovery).
  279. Run browser-based refresh on a timer (cron/launchd). It needs a saved Chrome profile from a prior
  280. `nlm login`, and does not apply when `NOTEBOOKLM_COOKIES` is set as an
  281. environment variable (that value overrides saved credentials).
  282. ### Enterprise Authentication (Gemini Notebook Enterprise)
  283. For organizations using **Gemini Notebook Enterprise** via Google Cloud, ask your Enterprise administrator for the project ID or number, the deployment location/multi-region, and confirmation that your account has access. The current documented host is `notebook.cloud.google.com`; older deployments may use `notebooklm.cloud.google.com` or `vertexaisearch.cloud.google.com`.
  284. 1. **Set Base URL, GCP Project ID & Location:**
  285. ```bash
  286. export NOTEBOOKLM_BASE_URL="https://notebook.cloud.google.com"
  287. # Required: your GCP project ID or project number from your administrator
  288. export NOTEBOOKLM_PROJECT_ID="your-gcp-project-id-or-number"
  289. # Optional: GCP location/multi-region from your administrator: global (default), us, or eu
  290. export NOTEBOOKLM_LOCATION="global"
  291. ```
  292. 2. **Save an Enterprise Auth Profile:**
  293. This opens the configured Enterprise URL in an isolated browser profile. Sign in with your organization account:
  294. ```bash
  295. nlm login --profile enterprise
  296. nlm login switch enterprise
  297. ```
  298. You can switch back to a personal profile at any time:
  299. ```bash
  300. unset NOTEBOOKLM_BASE_URL NOTEBOOKLM_PROJECT_ID NOTEBOOKLM_LOCATION
  301. nlm login switch personal
  302. ```
  303. 3. **Configure MCP Server with Enterprise Environment Variables:**
  304. When adding the MCP server to AI assistants (Claude, Cursor, etc.), pass `NOTEBOOKLM_BASE_URL`, `NOTEBOOKLM_PROJECT_ID`, and optionally `NOTEBOOKLM_LOCATION`:
  305. ```json
  306. {
  307. "mcpServers": {
  308. "gemini-notebook-mcp": {
  309. "command": "notebooklm-mcp",
  310. "env": {
  311. "NOTEBOOKLM_BASE_URL": "https://notebook.cloud.google.com",
  312. "NOTEBOOKLM_PROJECT_ID": "your-gcp-project-id-or-number",
  313. "NOTEBOOKLM_LOCATION": "global"
  314. }
  315. }
  316. }
  317. }
  318. ```
  319. Each profile gets its own isolated browser session, so you can be logged into multiple Google accounts simultaneously. Enterprise environment variables apply to the current process, so keep them in an Enterprise-only shell or MCP configuration when you also use a personal account.
  320. ### Standalone Auth Tool
  321. If you only need the MCP server (not the CLI):
  322. ```bash
  323. nlm login # Auto mode (launches browser)
  324. nlm login --manual # Manual file mode
  325. ```
  326. **How it works:** Auto mode launches a dedicated browser profile (supports Chrome, Arc, Dia, Comet, Brave, Edge, Chromium, Firefox, and more), you log in to Google, and cookies are extracted automatically. Your login persists for future auth refreshes.
  327. **Prefer a specific browser?** Set it with `nlm config set auth.browser chromium` (or `comet`, `dia`, `brave`, `arc`, `edge`, `chrome`, `firefox`, etc.). Falls back to auto-detection if the preferred named browser is not found. For any other Chromium-compatible browser, set its executable with `nlm config set auth.browser_path /path/to/browser` or `NLM_BROWSER_PATH`; an invalid explicit path fails closed instead of launching a different browser. When Chromium/CDP is unavailable, `auto` can fall back to Firefox.
  328. For detailed instructions and troubleshooting, see **[docs/AUTHENTICATION.md](docs/AUTHENTICATION.md)**.
  329. ## MCP Configuration
  330. > **⚠️ Context Window Warning:** This MCP provides **55 tools**. Disable it when not using Gemini Notebook to preserve context. In Claude Code: `@gemini-notebook-mcp` to toggle. To keep it on but expose only a subset, see [Selective tool exposure](docs/MCP_GUIDE.md#selective-tool-exposure).
  331. ### Automatic Setup (Recommended)
  332. The setup wizard is the recommended way to connect tools — see
  333. [Quick Start](#-quick-start) for what each menu option does:
  334. ```bash
  335. nlm setup
  336. ```
  337. MCP configuration goes to each app's user-level settings. Codex CLI and the
  338. ChatGPT desktop app share one MCP configuration on the same host. GitHub
  339. Copilot uses the VS Code user profile in the wizard; the direct command without
  340. `--scope user` targets the current workspace.
  341. For direct setup or scripts, keep using the existing commands:
  342. ```bash
  343. nlm setup add codex # Codex CLI / ChatGPT desktop
  344. nlm setup add github-copilot --scope user # VS Code user profile
  345. nlm setup add github-copilot # Current workspace
  346. nlm setup add claude-desktop --profile 3p # Relay AI / Claude 3P
  347. nlm setup list # Show MCP configuration status
  348. ```
  349. Claude Desktop setup only writes to profiles that are detected as present. If
  350. both regular and Relay AI/3P profiles exist, the CLI asks whether to configure
  351. regular, 3P, or both. For scripts, use `--profile regular|3p|both`. If no
  352. Claude Desktop profile is detected, nothing is created or changed.
  353. Removal uses the same profile selection, for example
  354. `nlm setup remove claude-desktop --profile regular`.
  355. Removal only offers detected profiles containing this MCP or a recognized
  356. legacy entry; unrelated MCP servers are left untouched.
  357. Before adding or removing the MCP, fully quit the selected Claude Desktop
  358. profile. The CLI detects running regular and Relay AI/3P instances and refuses
  359. to write while they are open, because Claude may rewrite the config and discard
  360. the change. Reopen Claude Desktop after setup completes.
  361. ### Install AI Skills (Optional)
  362. The wizard can install the prompting and workflow skill after MCP setup. It
  363. defaults to **All projects (user level)** and can instead install into the
  364. current project. Existing current or newer versions are preserved; older or
  365. unversioned skills require confirmation before replacement, with a backup made
  366. first.
  367. You can also manage skills directly. Supported local skill targets include
  368. **Cline**, **Antigravity**, **OpenClaw**, **Hermes**, **Codex**, **OpenCode**,
  369. **Claude Code**, and **Gemini CLI**.
  370. ```bash
  371. # Install skill files
  372. nlm skill install cline
  373. nlm skill install openclaw
  374. nlm skill install codex
  375. nlm skill install antigravity
  376. # Update skills
  377. nlm skill update
  378. ```
  379. User-level skill installation requires the target tool to be detected first;
  380. the CLI will not create a missing tool directory or install anyway. Use
  381. `--level project` when you intentionally want a project-local skill.
  382. #### Claude Desktop (Chat and Cowork) and claude.ai
  383. Claude Desktop's **Code** tab is Claude Code, so it uses the skill installed in
  384. `~/.claude/skills/`. The **Chat** and **Cowork** tabs, and claude.ai, only use
  385. skills uploaded to your Claude account. Create the upload file with the wizard
  386. (tick **Claude Desktop / claude.ai** in **Add the skill**) or directly:
  387. ```bash
  388. nlm skill package # saves ~/Downloads/nlm-skill.zip
  389. nlm skill package --output ~/Desktop
  390. ```
  391. Then in Claude Desktop (or claude.ai) open **Customize → Skills → Add**, pick
  392. `nlm-skill.zip`, and turn the skill on. Re-upload after updating `nlm` to get
  393. the latest skill. The MCP for Chat and Cowork comes from the normal Claude
  394. Desktop connection (`nlm setup` → **Add the MCP**).
  395. ### Remove from a tool
  396. ```bash
  397. nlm setup remove claude-code
  398. ```
  399. ### Using uvx (No Install Required)
  400. If you don't want to install the package, you can use `uvx` to run on-the-fly:
  401. ```bash
  402. # Run CLI commands directly
  403. uvx --from notebooklm-mcp-cli nlm setup add cursor
  404. uvx --from notebooklm-mcp-cli nlm login
  405. ```
  406. For tools that use JSON config, point them to uvx:
  407. ```json
  408. {
  409. "mcpServers": {
  410. "gemini-notebook-mcp": {
  411. "command": "uvx",
  412. "args": ["--from", "notebooklm-mcp-cli", "notebooklm-mcp"]
  413. }
  414. }
  415. }
  416. ```
  417. <details>
  418. <summary>Manual Setup (if you prefer)</summary>
  419. > **Tip:** Run `nlm setup add json` for an interactive wizard that generates the right JSON snippet for your tool.
  420. **Claude Code / Gemini CLI** support adding MCP servers via their own CLI:
  421. ```bash
  422. claude mcp add --scope user gemini-notebook-mcp notebooklm-mcp
  423. gemini mcp add --scope user gemini-notebook-mcp notebooklm-mcp
  424. ```
  425. **Cursor / Windsurf** resolve commands from your `PATH`, so the command name is enough:
  426. ```json
  427. {
  428. "mcpServers": {
  429. "gemini-notebook-mcp": {
  430. "command": "notebooklm-mcp"
  431. }
  432. }
  433. }
  434. ```
  435. | Tool | Config Location |
  436. | -------- | ------------------------------------- |
  437. | Cursor | `~/.cursor/mcp.json` |
  438. | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
  439. **GitHub Copilot (VS Code workspace)** uses `.vscode/mcp.json` with a top-level `servers` key:
  440. ```json
  441. {
  442. "servers": {
  443. "gemini-notebook-mcp": {
  444. "command": "notebooklm-mcp",
  445. "args": []
  446. }
  447. }
  448. }
  449. ```
  450. **Claude Desktop** may not resolve `PATH` — use the full path to the binary:
  451. ```json
  452. {
  453. "mcpServers": {
  454. "gemini-notebook-mcp": {
  455. "command": "/full/path/to/notebooklm-mcp"
  456. }
  457. }
  458. }
  459. ```
  460. Find your path with: `which notebooklm-mcp`
  461. | Tool | Config Location |
  462. | --------------------------------- | -------------------------------------------------------------------------------------------------- |
  463. | Claude Desktop (macOS current/3P) | `~/Library/Application Support/Claude-3p/claude_desktop_config.json` |
  464. | Claude Desktop (macOS legacy) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
  465. | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` (an unambiguous MSIX path is detected automatically) |
  466. | Claude Desktop (Windows 3P) | `%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json` |
  467. | Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
  468. | Claude Desktop (Linux 3P) | `${XDG_CONFIG_HOME:-~/.config}/Claude-3p/claude_desktop_config.json` |
  469. | GitHub Copilot | `.vscode/mcp.json` |
  470. </details>
  471. 📚 **Full configuration details:** [MCP Guide](docs/MCP_GUIDE.md) — Server options, environment variables, HTTP transport, and context window management. For Claude web/mobile and public deployment, read [Remote MCP Deployment](docs/REMOTE_MCP.md) first.
  472. ## What You Can Do
  473. Simply chat with your AI tool (Claude Code, Cursor, Gemini CLI) using natural language. Here are some examples:
  474. ### Research & Discovery
  475. - "List all my Gemini Notebook notebooks"
  476. - "Create a new notebook called 'AI Strategy Research'"
  477. - "Start web research on 'enterprise AI ROI metrics' and show me what sources it finds"
  478. - "Do a deep research on 'cloud marketplace trends' and import the top 10 sources"
  479. - "Search my Google Drive for documents about 'product roadmap' and create a notebook"
  480. ### Adding Content
  481. - "Add this URL to my notebook: https://example.com/article"
  482. - "Add this YouTube video about Kubernetes to the notebook"
  483. - "Add my meeting notes as a text source to this notebook"
  484. - "Import this Google Doc into my research notebook"
  485. ### AI-Powered Analysis
  486. - "What are the key findings in this notebook?"
  487. - "Summarize the main arguments across all these sources"
  488. - "What does this source say about security best practices?"
  489. - "Get an AI summary of what this notebook is about"
  490. - "Configure the chat to use a learning guide style with longer responses"
  491. _(All queries sent from CLI or MCP automatically persist in your Gemini Notebook web UI chat history!)_
  492. ### Content Generation
  493. - "Create an audio podcast overview of this notebook in deep dive format"
  494. - "Generate a video explainer with classic visual style"
  495. - "Make a short vertical video overview of the key idea"
  496. - "Make a briefing doc from these sources"
  497. - "Create flashcards for studying, medium difficulty"
  498. - "Generate an infographic in landscape orientation with professional style"
  499. - "Build a mind map from my research sources"
  500. - "Create a slide deck presentation from this notebook"
  501. ### Smart Management
  502. - "Check which Google Drive sources are out of date and sync them"
  503. - "Show me all the sources in this notebook with their freshness status"
  504. - "Delete this source from the notebook"
  505. - "Check the status of my audio overview generation"
  506. - "Check this specific artifact without listing every Studio item"
  507. - "List only the generated videos in this notebook"
  508. ### Sharing & Collaboration
  509. - "Show me the sharing settings for this notebook"
  510. - "Make this notebook public so anyone with the link can view it"
  511. - "Disable public access to this notebook"
  512. - "Invite user@example.com as an editor to this notebook"
  513. - "Add a viewer to my research notebook"
  514. **Pro tip:** After creating studio content (audio, video, reports, etc.), poll the status to get download URLs when generation completes.
  515. ## Authentication Lifecycle
  516. | Component | Duration | Refresh |
  517. | ---------- | --------------- | ---------------------------------------------------- |
  518. | Cookies | ~2-4 weeks | Auto-refresh via headless browser (if profile saved) |
  519. | CSRF Token | ~minutes | Auto-refreshed on every request failure |
  520. | Session ID | Per MCP session | Auto-extracted on MCP start |
  521. **v0.1.9+**: The server now automatically handles token expiration:
  522. 1. Refreshes CSRF tokens immediately when expired
  523. 2. Reloads cookies from disk if updated externally
  524. 3. Runs headless browser auth if profile has saved login
  525. You can also call `refresh_auth()` to explicitly reload and validate tokens, or
  526. `refresh_auth(profile="work")` to refresh a named saved account without
  527. switching the MCP server's active account.
  528. If automatic refresh fails (Google login fully expired), run `nlm login` again.
  529. For suspected browser-bound auth replay failures, run `nlm doctor auth-replay`.
  530. If the `cdp_in_page` probe succeeds while normal replay fails, see
  531. [Experimental browser-backed RPC transport](docs/AUTHENTICATION.md#experimental-browser-backed-rpc-transport).
  532. ## Troubleshooting
  533. ### `uv tool upgrade` Not Installing Latest Version
  534. **Symptoms:**
  535. - Running `uv tool upgrade notebooklm-mcp-cli` installs an older version (e.g., 0.1.5 instead of 0.1.9)
  536. - `uv cache clean` doesn't fix the issue
  537. **Why this happens:** `uv tool upgrade` respects version constraints from your original installation. If you initially installed an older version or with a constraint, `upgrade` stays within those bounds by design.
  538. **Fix — Force reinstall:**
  539. ```bash
  540. uv tool install --force notebooklm-mcp-cli
  541. ```
  542. This bypasses any cached constraints and installs the absolute latest version from PyPI.
  543. **Verify:**
  544. ```bash
  545. uv tool list | grep notebooklm
  546. # Should show: notebooklm-mcp-cli v0.1.9 (or latest)
  547. ```
  548. ## Limitations
  549. - **Rate limits**: Chat and Studio usage is metered as compute against a rolling (~5h) window and a weekly cap, scaled by plan tier. Run `nlm usage` to see what is left and when it resets
  550. - **No official support**: API may change without notice
  551. - **Cookie expiration**: Need to re-extract cookies every few weeks
  552. ## Contributing
  553. See [CLAUDE.md](CLAUDE.md) for detailed API documentation and how to add new features.
  554. ## Vibe Coding Alert
  555. Full transparency: this project was built by a non-developer using AI coding assistants. If you're an experienced Python developer, you might look at this codebase and wince. That's okay.
  556. The goal here was to scratch an itch - programmatic access to Gemini Notebook - and learn along the way. The code works, but it's likely missing patterns, optimizations, or elegance that only years of experience can provide.
  557. **This is where you come in.** If you see something that makes you cringe, please consider contributing rather than just closing the tab. This is open source specifically because human expertise is irreplaceable. Whether it's refactoring, better error handling, type hints, or architectural guidance - PRs and issues are welcome.
  558. Think of it as a chance to mentor an AI-assisted developer through code review. We all benefit when experienced developers share their knowledge.
  559. ## Credits
  560. Special thanks to:
  561. - **Le Anh Tuan** ([@latuannetnam](https://github.com/latuannetnam)) for contributing the HTTP transport, debug logging system, and performance optimizations.
  562. - **David Szabo-Pele** ([@davidszp](https://github.com/davidszp)) for the `source_get_content` tool and Linux auth fixes.
  563. - **saitrogen** ([@saitrogen](https://github.com/saitrogen)) for the research polling query fallback fix.
  564. - **devnull03** ([@devnull03](https://github.com/devnull03)) for multi-browser CDP authentication support (Arc, Brave, Edge, Chromium, Vivaldi, Opera).
  565. - **VooDisss** ([@VooDisss](https://github.com/VooDisss)) for multi-browser authentication improvements.
  566. - **codepiano** ([@codepiano](https://github.com/codepiano)) for the configurable DevTools timeout for the auth CLI.
  567. - **Tony Hansmann** ([@997unix](https://github.com/997unix)) for contributing the `nlm setup` and `nlm doctor` commands and CLI Guide documentation.
  568. - **Fabiana Furtado** ([@fabianafurtadoff](https://github.com/fabianafurtadoff)) for batch operations, cross-notebook query, pipelines, and smart select/tagging (PR #90).
  569. - **Amy-Ra-lph** ([@Amy-Ra-lph](https://github.com/Amy-Ra-lph)) for security hardening: TOCTOU-safe credential storage, sensitive cookie redaction from debug logs, and pinning all CI actions to full commit SHAs (PRs #205–207).
  570. - **Kyle Brodeur** ([@kylebrodeur](https://github.com/kylebrodeur)) for WSL2 authentication support with Windows Chrome integration (PR #138).
  571. - **Robiton** ([@Robiton](https://github.com/Robiton)) for enterprise Gemini Notebook support via configurable base URL (PR #114).
  572. - **pjeby** ([@pjeby](https://github.com/pjeby)) for connection pooling and fast startup improvements (PR #54).
  573. - **beausea** ([@beausea](https://github.com/beausea)) for making the interface language configurable via the `NOTEBOOKLM_HL` environment variable (PR #59).
  574. - **JumpLao** ([@JumpLao](https://github.com/JumpLao)) for extended audio, video, and image format support (PR #82).
  575. - **cbruyndoncx** ([@cbruyndoncx](https://github.com/cbruyndoncx)) for including `cited_text` passages in query output (PR #81).
  576. - **zxyasfas** ([@zxyasfas](https://github.com/zxyasfas)) for cited-only research import (PR #188).
  577. - **Serdar Akın** ([@SERDAR-AKIN](https://github.com/SERDAR-AKIN)) for the multi-probe `AuthHealthChecker` that fixes false `"stale"` reports for semi-stale cookies (PR #219).
  578. ## Star History
  579. [![Star History Chart](https://star-history.dera.page/svg?repos=jacob-bd/gemini-notebook-mcp-cli&type=Date)](https://star-history.dera.page/#jacob-bd/gemini-notebook-mcp-cli&Date)
  580. ## License
  581. [MIT License](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.