mathruffian-dot/opencode-lazy-packs/03-notebooklm

OpenCode 懶人包 #03：連接 Gemini Notebook（原 NotebookLM）

🔴 產品在 2026-07-16 改名了。

Google 把 Gemini Notebook 更名為 Gemini Notebook，介面換成藍紫色的 Gemini 漸層 logo。

同一個產品、同一批筆記本，不用搬家、不用重建。

對本包的實際影響：

| 項目 | 有沒有變 |

|---|---|

| 產品名稱與 logo | ✅ 改了——使用者畫面上看到的是「Gemini Notebook」 |

| PyPI 套件名 notebooklm-mcp-cli | ❌ 沒變 |

| CLI 指令 nlm、MCP 執行檔 notebooklm-mcp | ❌ 沒變 |

| GitHub repo | ⚠️ 搬到 jacob-bd/gemini-notebook-mcp-cli（舊網址會轉址） |

所以底下的安裝指令全部照舊可用。 只有跟使用者講話時要說「Gemini Notebook」，

否則他打開畫面會找不到你說的那個名字。

📌 本懶人包可獨立執行：會自動檢查並安裝所需工具。

這個懶人包會幫你做什麼？

讓 OpenCode 能夠操作 Gemini Notebook：

• 建立 notebook、上傳資料來源
• 產生教學簡報（Slide Deck）、資訊圖表（Infographic）
• 產生音訊概覽、影片概覽、心智圖、測驗等
• 所有成品自動下載到電腦裡的指定資料夾

原理說明

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

因為 Gemini Notebook 沒有官方 API，中間需要一個「翻譯官」模擬瀏覽器操作。

裝一次，會得到兩個指令（同一個套件提供，不要以為裝錯了）：

⚠️ 這兩個不能互換。opencode.json 裡要填的是 `notebooklm-mcp`，不是 nlm（詳見步驟五）。

⚠️ 開始之前：最容易裝錯的一件事

🚨 npm 上真的有一個叫 `nlm` 的套件，但它跟 Gemini Notebook 一點關係都沒有（是 2021 年停更的另一個專案）。

打 npm install nlm 不會報錯，會裝得好好的——然後你會拿著一個完全無關的工具，花一小時找不到問題出在哪。

這一包只用 PyPI 的 `notebooklm-mcp-cli`。

先備條件

• [ ] uv 已安裝（由 00-env-setup 負責）——本包主要靠它
• [ ] Python 3.11 以上（走 pip 路線才需要自己確認；走 uv 路線 uv 會自己處理）
• [ ] OpenCode 已安裝，且已完成 01-connect-model
• [ ] 有 Google 帳號
• [ ] 電腦有網路連線

📌 本包不需要 Node.js。notebooklm-mcp 是 Python 工具，不透過 npx 啟動。

安裝方式二選一

方式 A：uv（獨立環境，推薦）

uv tool install notebooklm-mcp-cli

方式 B：pip（全域安裝）

pip install notebooklm-mcp-cli

兩種只選一種。混裝會讓電腦上出現兩份、升級時互相打架。研習現場一律走 A。

請 OpenCode 幫我執行以下步驟

⚠️ 把這份檔案的內容貼給 OpenCode，它會自動執行。遇到需要手動操作的地方會暫停指示你。

步驟零：環境檢查

1. 確認作業系統：Windows / macOS / Linux
2. 確認網路連線正常
3. 檢查 uv：uv --version。沒有的話，步驟一補裝
4. 確認 OpenCode 叫得動：opencode --version（沒有請回 00-env-setup）

步驟一：安裝 uv（如果沒裝）

📌 uv 安裝的權威版本在 `00-env-setup` 步驟 7。這裡只是讓本包可以獨立跑完，兩邊有出入以 00-env-setup 為準。

Windows（PowerShell）：

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

macOS：

brew install uv

Linux / 通用備案：

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

確認：uv --version → 印出版本號。

步驟二：安裝 Gemini Notebook 工具

uv tool install notebooklm-mcp-cli

（用 pip 的話：pip install notebooklm-mcp-cli）

驗證兩個指令都在：

nlm --version
notebooklm-mcp --help

預期輸出：

• nlm --version → 印出一行 nlm version …
• notebooklm-mcp --help → 印出一段 usage: 說明，裡面看得到 --transport {stdio,http,sse}

失敗長相：command not found / 無法辨識… → 不要重裝，先做步驟三。

步驟三：確認安裝位置與 PATH

✅ 安裝完，執行檔會出現在這裡，這是正常且正確的位置：

uv tool install 本來就裝在這裡。不要刪、不要搬、不要「換成別的路徑」。

🚨 如果你看過任何教學叫你「避開 `.local\bin` 底下的執行檔」——那是錯的。

照做會把唯一正確的安裝刪掉，然後怎麼修都修不好。

查實際完整路徑：

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

# macOS / Linux
which nlm; which notebooklm-mcp

如果指令找不到，不是裝壞了，是 PATH 還沒生效。 依序試：

1. 關掉終端機，開一個新的，再試一次 —— 九成的狀況這樣就好了。
2. 不想關視窗的話，Windows 可以就地刷新 PATH：

``powershell $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User") ` macOS / Linux：source ~/.zshrc（或 source ~/.bashrc`）

1. 還是找不到 → 讓 uv 把自己的 bin 目錄正式寫進 PATH，然後重開終端機：

``bash uv tool update-shell ``

步驟四：登入 Google 帳號

nlm login

🖐️ 這一步需要你本人操作：瀏覽器會開啟 Google 登入頁面，選擇你的 Google 帳號完成授權。Agent 請停下來等使用者回報完成。

登入後驗證：

nlm doctor

預期輸出：診斷結果，認證狀態顯示正常。顯示未認證就重跑 nlm login。

📌 指令會隨版本演進，本文件刻意不釘死版本號。

nlm 目前的完整指令清單，一律以 `nlm --help` 的輸出為準；子指令的選項用 nlm <指令> --help 查。

如果下面寫的某個指令在你的版本上不存在，先跑 nlm --help 看它改叫什麼，不要硬套本文件。

步驟五：設定 MCP 連接

方式 A：讓工具自己寫（推薦，最省事）

nlm setup add opencode

它會自動找到 ~/.config/opencode/opencode.json，把設定用正確格式寫進去，連逾時設定都一併處理好。

確認寫入結果：

nlm setup list

這個指令也支援其他 AI 工具（claude-code、gemini、cursor 等）。用 nlm setup add --help 看清單。

方式 B：手動寫設定檔

編輯 ~/.config/opencode/opencode.json，在 mcp 區塊加入：

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

三個一定要對的地方：

如果加了 `timeout` 還是逾時，再補一個全域設定（跟 mcp 同一層）：

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

如果 PATH 有問題（步驟三試過還是叫不動），可以在 command 直接填步驟三查到的完整路徑：

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

Windows 路徑的反斜線在 JSON 裡要寫成兩條 \\。

步驟六：建立本地資料夾

在文件資料夾下建立以下目錄結構：

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

建立完成後，告知使用者資料夾的完整路徑。

步驟七：重啟並驗證連接

🖐️ 完全關閉 OpenCode，然後重新開啟（改完設定檔沒生效時，先重開再說）。

驗證指令（這是最可靠的方式，不要用「問問看 agent」猜）：

opencode mcp list

預期輸出：清單裡有 notebooklm 這一列，狀態顯示 `✓ connected`。

連不上的話看細節：

opencode mcp debug notebooklm

看到 ✓ connected 之後，再對 OpenCode 說：

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

能列出（即使是空的）代表整條路都通了。

步驟八：功能測試

1. 建立一個名為「測試筆記本」的 notebook
2. 確認建立成功
3. 刪除這個測試筆記本
4. ✅ 「全部完成！OpenCode 已成功連接 Gemini Notebook。」

🤖 機器可判讀的成功訊號

執行完請完整輸出下面這個區塊，讓後續的 agent（或「一次全裝」那一包）可以直接判讀，不必讀懂中文說明。

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

判定規則（agent 請照這個判斷，不要自行認定）：

⚠️ mcp_timeout=missing 即使其他全綠，也請降為 PARTIAL 並提醒使用者補上——現場很可能在第一次跑大工作時才炸。

完成回報格式

## Gemini Notebook 連接完成
 
| 項目 | 狀態 |
|------|------|
| uv | ✅ / ❌ |
| notebooklm-mcp-cli（`nlm` + `notebooklm-mcp`） | ✅ / ❌ |
| PATH 生效（兩個指令都叫得動） | ✅ / ❌ |
| Google 登入（`nlm doctor`） | ✅ / ❌ |
| MCP 設定寫入 opencode.json | ✅ / ❌ |
| `timeout` 已設定 | ✅ / ❌ |
| `opencode mcp list` 顯示 ✓ connected | ✅ / ❌ |
| 筆記本讀取測試 | ✅ / ❌ |
| 本地資料夾 | ✅ / ⏭️ 略過 |
 
-安裝路徑：<notebooklm-mcp 的完整路徑>
-需要你手動處理的事：（沒有 / 條列）

如果安裝失敗，如何重來

對 OpenCode 說：「上次 Gemini Notebook 懶人包執行失敗了，幫我清除設定，重新跑一次。」

復原步驟：

1. 從 opencode.json 的 mcp 區塊移除 notebooklm 項目

（或用 nlm setup remove opencode）

1. 移除工具：uv tool uninstall notebooklm-mcp-cli（pip 路線用 pip uninstall notebooklm-mcp-cli）
2. 清除登入：

> ⚠️ 沒有 `nlm logout` 這個指令，打了只會得到 No such command。

• 想換 Google 帳號重登：nlm login --clear
• 想整個清乾淨：刪掉設定資料夾
• Windows：%USERPROFILE%\.notebooklm-mcp-cli\
• macOS / Linux：~/.notebooklm-mcp-cli/

1. 從步驟零重新開始

常見問題

相關懶人包

• 00-env-setup — uv 的安裝權威版本，以及MCP 通用守則（逾時、設定格式、金鑰安全）
• 04-obsidian — 另一條把素材收進第二大腦的路線
• 02-file-toolkit — 把 Gemini Notebook 產出的檔案再加工