opencode-notebooklm

OpenCode Quick Start #03: Connect Gemini Notebook (formerly NotebookLM)

🔴 The product was renamed on 2026-07-16. Google renamed Gemini Notebook to Gemini Notebook, and the interface switched to the blue-purple Gemini gradient logo. Same product, same notebooks, no need to move or rebuild anything.

The actual impact on this pack:

Item Changed?

Product name and logo ✅ Changed— what users see on screen is "Gemini Notebook"

PyPI package name notebooklm-mcp-cli ❌ Unchanged

CLI command nlm, MCP executable notebooklm-mcp ❌ Unchanged

GitHub repo ⚠️ Moved to jacob-bd/gemini-notebook-mcp-cli(the old URL will redirect)

So all the installation commands below still work as-is. Only when talking to users should you say "Gemini Notebook", otherwise when they open the screen they won't find the name you mentioned.

Item	Changed?
Product name and logo	✅ Changed— what users see on screen is "Gemini Notebook"
PyPI package name `notebooklm-mcp-cli`	❌ Unchanged
CLI command `nlm`, MCP executable `notebooklm-mcp`	❌ Unchanged
GitHub repo	⚠️ Moved to `jacob-bd/gemini-notebook-mcp-cli`(the old URL will redirect)

📌 This quick start pack can run standalone: it will automatically check for and install the required tools.

What will this quick start pack do for you?

Enable OpenCode to operate Gemini Notebook:

Create notebooks, upload data sources
Generate slide decks and infographics
Generate audio overviews, video overviews, mind maps, quizzes, etc.
All outputs are automatically downloaded to a specified folder on your computer

How it works

OpenCode ←(MCP 協定)→ notebooklm-mcp（翻譯官）←(Google 登入)→ Gemini Notebook

Because Gemini Notebook has no official API, a "translator" is needed in between to simulate browser operations.

Install once, get two commands(provided by the same package, don't think you installed the wrong thing):

Command	Who uses it	What it does
`nlm`	You, type it in the terminal	Log in, diagnose, manually operate notebooks
`notebooklm-mcp`	OpenCode, starts automatically in the background	The MCP server itself

⚠️ These two are not interchangeable.opencode.json What goes in notebooklm-mcpis nlm(see step five).

⚠️ Before you start: the easiest thing to get wrong

	✅ Correct	❌ Wrong
Where the package is	PyPI(Python's package repository)	npm (Node's package repository)
Package name	`notebooklm-mcp-cli`	`nlm`
Install command	`uv tool install notebooklm-mcp-cli`	`npm install nlm`

🚨 There really is a package on npm called nlm , but it has nothing to do with Gemini Notebook(it's another project that stopped updating in 2021). Running npm install nlm won't throw an error, it will install just fine—and then you'll be holding a completely unrelated tool, spending an hour unable to find where the problem is. This pack only uses PyPI's notebooklm-mcp-cli。

Prerequisites

uv installed(handled by 00-env-setup )—this pack mainly relies on it
Python 3.11 or later (you only need to check this yourself if you go the pip route; if you go the uv route, uv handles it itself)
OpenCode is installed, and 01-connect-model
You have a Google account
Your computer has a network connection

📌 This package does not require Node.js。notebooklm-mcp is a Python tool, not launched through npx .

Choose one of two installation methods

Method A: uv (isolated environment, recommended)

uv tool install notebooklm-mcp-cli

Method B: pip (global installation)

pip install notebooklm-mcp-cli

twochoose only one. Mixing them will leave two copies on your computer that fight each other during upgrades. At the workshop, always use A.

Ask OpenCode to run the following steps for me

⚠️ Paste the contents of this file to OpenCode, and it will run them automatically. When manual action is needed, it will pause and instruct you.

Step zero: environment check

Confirm the operating system：Windows / macOS / Linux
Confirm the network connection is working
Check uv：uv --version. If not present, install it in step one
Confirm OpenCode can be invoked：opencode --version(if not, go back to 00-env-setup）

Step one: install uv (if not installed)

📌 The authoritative version of the uv installation is in 00-env-setup step 7. This is only so this package can run through independently; if there is any discrepancy, 00-env-setup takes precedence.

Windows（PowerShell）：

winget install --id astral-sh.uv --exact --accept-source-agreements --accept-package-agreements

macOS：

brew install uv

Linux / general fallback：

curl -LsSf https://astral.sh/uv/install.sh | sh

Confirm:uv --version → prints the version number.

Step two: install the Gemini Notebook tool

uv tool install notebooklm-mcp-cli

(if using pip:pip install notebooklm-mcp-cli）

Verify both commands are present：

nlm --version
notebooklm-mcp --help

Expected output：

nlm --version → prints one line of nlm version …
notebooklm-mcp --help → prints a section of usage: description, in which you can see --transport {stdio,http,sse}

What failure looks like：command not found / 無法辨識… → do not reinstall, do step three first.

Step three: confirm the installation location and PATH

✅ After installation, the executable will appear here; this is the normal and correct location:

System	Location
Windows	`%USERPROFILE%\.local\bin\`(i.e. `C:\Users\<你的帳號>\.local\bin\`）
macOS / Linux	`~/.local/bin/`

uv tool install is originally installed here.Do not delete, do not move, do not "change it to another path".

🚨 If you have seen any tutorial telling you to "avoid the executable under .local\bin "—that is wrong. Following it will delete the only correct installation, and then no matter how you fix it, it will not work.

Check the actual full path：

# Windows（PowerShell）
where.exe nlm; where.exe notebooklm-mcp

# macOS / Linux
which nlm; which notebooklm-mcp

If the command cannot be found, it is not that the installation is broken; it is that PATH has not taken effect yet. Try in order:

Close the terminal and open a new one, then try again — in ninety percent of cases this solves it.

If you do not want to close the window, on Windows you can refresh PATH in place:

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

macOS / Linux：source ~/.zshrc(or source ~/.bashrc）

Still cannot find it → have uv formally write its own bin directory into PATH, thenrestart the terminal：
```
uv tool update-shell
```

Step four: sign in to your Google account

nlm login

🖐️ This step requires you to do it yourself: the browser will open the Google sign-in page; choose your Google account to complete authorization. Agent, please stop and wait for the user to report completion.

Verify after signing in:

nlm doctor

Expected output: diagnostic result, authentication status shows normal. If it shows unauthenticated, rerun nlm login。

📌 Commands evolve with versions, so this document deliberately does not pin down version numbers. nlm For the current complete command list,always use the output of nlm --help as the standard; for subcommand options, use nlm <指令> --help to check. If a command written below does not exist in your version, first run nlm --help to see what it is now called, and do not force this document to apply.

Step 5: Configure MCP Connection

Method A: Let the tool write it itself (recommended, least effort)

nlm setup add opencode

It will automatically find ~/.config/opencode/opencode.json, write the settings inthe correct format, and even handle timeout settings along with it.

Confirm the write result:

nlm setup list

This command also supports other AI tools (claude-code、gemini、cursor , etc.). Use nlm setup add --help to view the list.

Method B: Manually write the configuration file

Edit ~/.config/opencode/opencode.json, and in the mcp block add:

{
  "mcp": {
    "notebooklm": {
      "type": "local",
      "command": ["notebooklm-mcp"],
      "enabled": true,
      "timeout": 300000
    }
  }
}

Three things that must be correct:

Key point	Description
`command` Fill in `notebooklm-mcp`	not `nlm`。`nlm` is a CLI for humans to type, and it does not have the `--transport` option; writing it as `["nlm", "--transport", "stdio"]` will directly cause startup failure
`command` isarray	OpenCode's `command` only accepts an array, andthere is no `args` field(copying Claude Code's way of writing it will break, see `00-env-setup` 's general MCP guidelines)
Must add `timeout`	OpenCode's MCP timeout defaults to only 5000 milliseconds (5 seconds). Gemini Notebook operations (generating slides, generating videos, queries) often take tens of seconds to several minutes; without adding it, it will definitely time out.`300000` = 5 minutes

If you added timeout and it still times out, then add a global setting (at the same level as mcp ):

{
  "experimental": {
    "mcp_timeout": 300000
  }
}

If there is a PATH problem(if you tried Step 3 and it still cannot be invoked), you can directly fill in command with thefull path：

"command": ["C:\\Users\\<你的帳號>\\.local\\bin\\notebooklm-mcp.exe"]

Backslashes in Windows paths must be written as two \\。

Step 6: Create Local Folders

Create the following directory structure under the Documents folder:

Documents/
  └── Gemini Notebook/
      ├── slides/          ← 簡報（Slide Deck）
      ├── infographics/    ← 資訊圖表
      ├── audio/           ← 音訊概覽
      ├── video/           ← 影片概覽
      ├── docs/            ← 報告文件
      ├── sheets/          ← 試算表
      ├── mindmaps/        ← 心智圖
      └── quizzes/         ← 測驗與閃卡

After creation is complete, inform the user of the full path of the folder.

Step 7: Restart and Verify Connection

🖐️ Completely close OpenCode, then reopen it(if the configuration file changes do not take effect, restart first before anything else).

Verification command (this is the most reliable way; do not use "ask the agent" to guess)：

opencode mcp list

Expected output: the list contains the notebooklm row, and the status shows ✓ connected。

If it cannot connect, look at the details:

opencode mcp debug notebooklm

After seeing ✓ connected , then say to OpenCode:

請列出我所有的 Gemini Notebook 筆記本。

Being able to list (even if empty) means the entire path is working.

Step 8: Functional Test

Create a notebook named "Test Notebook"
Confirm creation succeeded
Delete this test notebook
✅ "All done! OpenCode has successfully connected to Gemini Notebook."

🤖 Machine-readable success signal

After execution, output the following block in full, so that subsequent agents (or the "install everything at once" package) can directly interpret it without needing to understand the Chinese instructions.

=== OPENCODE_NOTEBOOKLM ===
result=PASS                    # PASS | PARTIAL | FAIL
os=windows                     # windows | macos | linux
uv=ok                          # ok | missing
nlm=<nlm --version 的輸出>       # 版本字串 | missing
mcp_server_bin=<完整路徑>        # notebooklm-mcp 的實際路徑 | missing
login=ok                       # ok | failed（依 nlm doctor）
mcp_config=ok                  # ok | failed（opencode.json 的 mcp.notebooklm 已寫入）
mcp_timeout=300000             # 實際寫入的毫秒數 | missing
mcp_connected=yes              # yes | no（opencode mcp list 顯示 ✓ connected）
notebook_list=ok               # ok | failed
local_folders=ok               # ok | skipped
=== END ===

Decision rules (agents should follow this judgment, do not decide on your own):

Result	Condition
`PASS`	`mcp_connected=yes` and `login=ok` and `notebook_list=ok`
`PARTIAL`	The tool is installed (`nlm` has a version number), but at least one of login or connection is missing
`FAIL`	`nlm=missing`—the tool was not installed at all

⚠️ mcp_timeout=missing Even if everything else is green, please downgrade to PARTIAL and remind the user to fill it in—it is very likely to blow up only when running a big job for the first time.

Completion report format

## Gemini Notebook 連接完成

| 項目 | 狀態 |
|------|------|
| uv | ✅ / ❌ |
| notebooklm-mcp-cli（`nlm` + `notebooklm-mcp`） | ✅ / ❌ |
| PATH 生效（兩個指令都叫得動） | ✅ / ❌ |
| Google 登入（`nlm doctor`） | ✅ / ❌ |
| MCP 設定寫入 opencode.json | ✅ / ❌ |
| `timeout` 已設定 | ✅ / ❌ |
| `opencode mcp list` 顯示 ✓ connected | ✅ / ❌ |
| 筆記本讀取測試 | ✅ / ❌ |
| 本地資料夾 | ✅ / ⏭️ 略過 |

- 安裝路徑：<notebooklm-mcp 的完整路徑>
- 需要你手動處理的事：（沒有 / 條列）

If installation fails, how to start over

Say to OpenCode: "Last time the Gemini Notebook quick package failed to run. Help me clear the settings and run it again."

Recovery steps:

From opencode.json 's mcp block, remove the notebooklm entry (or use nlm setup remove opencode）
Remove the tool:uv tool uninstall notebooklm-mcp-cli(for the pip route use pip uninstall notebooklm-mcp-cli）
Clear login：

⚠️ there is no nlm logout this command, typing it will only get No such command。
- Want to switch Google accounts and log in again:nlm login --clear
- Want to clean everything up: delete the settings folder
  - Windows：%USERPROFILE%\.notebooklm-mcp-cli\
  - macOS / Linux：~/.notebooklm-mcp-cli/
Start over from step zero

Common questions

Question	Solution
`nlm: command not found`	It is not a broken installation, it is that PATH has not taken effect. Close the terminal and reopen it; if it still does not work, see points 2 and 3 of step three
I see `.local\bin` in `notebooklm-mcp.exe`, is it installed in the wrong place?	No, that is the correct location. `uv tool install` is originally installed there, do not delete it
`uv: command not found`	On Windows, restart PowerShell; on macOS/Linux `source ~/.zshrc` or `source ~/.bashrc`
I followed an online tutorial and typed `npm install nlm`	and installed a completely unrelated package.`npm uninstall -g nlm` remove it and use `uv tool install notebooklm-mcp-cli`
After logging in, `nlm doctor` shows unauthenticated	Run `nlm login`again, and confirm that the browser did indeed log in successfully
The browser did not open automatically	Manually open https://notebooklm.google.com/ to confirm you are logged in, or try `nlm login --manual`(use `nlm login --help` to confirm which options your version supports)
Want to switch to another Google account	`nlm login --clear` log in again; for multiple accounts you can use `nlm login switch <profile>`
`opencode mcp list` there is no `notebooklm` this line	The setting was not written in, or was written at the wrong level. Confirm that `mcp` is inthe top level, not nested inside another entry; or directly run `nlm setup add opencode` and let it write it for you
`opencode mcp list` shows connection failure / timeout	①`command` Was it mistakenly filled in as `nlm`? It should be `notebooklm-mcp` ②Has `"timeout": 300000`been added? ③Run `opencode mcp debug notebooklm` to see the details
The config file was changed but there is no effect	Completely close OpenCode and reopen it; if it still does not work, use `opencode mcp list` to confirm what it is actually reading
A large job gets interrupted halfway through (generating videos, generating slides)	The timeout is too short. Increase `timeout` , and add the global `experimental.mcp_timeout`(see step five)
`ModuleNotFoundError: No module named 'notebooklm_tools'`	The installation got broken (usually by manually moving files).`uv tool uninstall notebooklm-mcp-cli` then reinstall;do notmove the files in `.local\bin` yourself
Incorrect command format on Windows	Use PowerShell, not CMD; do not use `&&` to chain commands; use `;`
`nlm list` or similar commands show garbled text or `UnicodeDecodeError`	Set `$env:PYTHONIOENCODING = "utf-8"` then run. This is a known issue with the cp950 encoding on Chinese versions of Windows and does not affect MCP functionality
The web interface has been renamed	Google has been adjusting the branding and URL of Gemini Notebook. The tool automatically handles both the old and new domains, so the commands do not need to be changed; if it really cannot connect, run `nlm doctor` to check the diagnostics

Related quick guides

00-env-setup — the authoritative version of the uv installation, andGeneral MCP guidelines(timeouts, config format, key security)
04-obsidian — another route for collecting material into a second brain
02-file-toolkit — further processing files produced by Gemini Notebook