opencode-notebooklm

OpenCode 懶人包 #03：連接 NotebookLM

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

---

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

讓 OpenCode 能夠操作 Google NotebookLM：

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

---

原理說明

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

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

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

| 指令 | 誰在用 | 做什麼 | |------|--------|--------| | nlm | 你，在終端機打 | 登入、診斷、手動操作筆記本 | | notebooklm-mcp | OpenCode，自動在背後啟動 | MCP server 本體 |

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

---

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

| | ✅ 正確 | ❌ 錯誤 | |--|---------|---------| | 套件在哪 | PyPI（Python 的套件庫） | npm（Node 的套件庫） | | 套件名稱 | notebooklm-mcp-cli | nlm | | 安裝指令 | uv tool install notebooklm-mcp-cli | ~~npm install nlm~~ |

🚨 npm 上真的有一個叫 nlm 的套件，但它跟 NotebookLM 一點關係都沒有（是 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 → 印出版本號。

---

步驟二：安裝 NotebookLM 工具

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

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

| 系統 | 位置 | |------|------| | Windows | %USERPROFILE%\.local\bin\（即 C:\Users\<你的帳號>\.local\bin\） | | macOS / Linux | ~/.local/bin/ |

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）
3. 還是找不到 → 讓 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
    }
  }
}

三個一定要對的地方：

| 重點 | 說明 | |------|------| | command 填 notebooklm-mcp | 不是 nlm。nlm 是給人打的 CLI，它沒有 --transport 這個選項；寫成 ["nlm", "--transport", "stdio"] 會直接啟動失敗 | | command 是陣列 | OpenCode 的 command 只吃陣列，而且沒有 args 欄位（照抄 Claude Code 的寫法會壞，見 00-env-setup 的 MCP 通用守則） | | 一定要加 timeout | OpenCode 的 MCP 逾時預設只有 5000 毫秒（5 秒）。NotebookLM 的操作（產簡報、產影片、查詢）動輒數十秒到數分鐘，不加必逾時。300000 = 5 分鐘 |

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

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

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

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

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

---

步驟六：建立本地資料夾

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

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

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

---

步驟七：重啟並驗證連接

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

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

opencode mcp list

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

連不上的話看細節：

opencode mcp debug notebooklm

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

請列出我所有的 NotebookLM 筆記本。

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

---

步驟八：功能測試

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

---

🤖 機器可判讀的成功訊號

執行完請完整輸出下面這個區塊，讓後續的 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 請照這個判斷，不要自行認定）：

| 結果 | 條件 | |------|------| | PASS | mcp_connected=yes 且 login=ok 且 notebook_list=ok | | PARTIAL | 工具裝好了（nlm 有版本號），但登入或連線至少缺一項 | | FAIL | nlm=missing——工具根本沒裝起來 |

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

---

完成回報格式

## NotebookLM 連接完成

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

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

---

如果安裝失敗，如何重來

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

復原步驟：

1. 從 opencode.json 的 mcp 區塊移除 notebooklm 項目 （或用 nlm setup remove opencode）
2. 移除工具：uv tool uninstall notebooklm-mcp-cli（pip 路線用 pip uninstall notebooklm-mcp-cli）
3. 清除登入： > ⚠️ 沒有 nlm logout 這個指令，打了只會得到 No such command。
4. 想換 Google 帳號重登：nlm login --clear
5. 想整個清乾淨：刪掉設定資料夾
6. Windows：%USERPROFILE%\.notebooklm-mcp-cli\
7. macOS / Linux：~/.notebooklm-mcp-cli/
8. 從步驟零重新開始

---

常見問題

| 問題 | 解法 | |------|------| | nlm: command not found | 不是裝壞了，是 PATH 沒生效。 關掉終端機重開；仍不行看步驟三第 2、3 點 | | 我在 .local\bin 看到 notebooklm-mcp.exe，是不是裝錯地方？ | 沒有錯，那就是正確位置。 uv tool install 本來就裝在那裡，不要刪 | | uv: command not found | Windows 重開 PowerShell；macOS/Linux source ~/.zshrc 或 source ~/.bashrc | | 我照網路教學打了 npm install nlm | 裝到的是完全無關的套件。npm uninstall -g nlm 移掉，改用 uv tool install notebooklm-mcp-cli | | 登入後 nlm doctor 顯示未認證 | 重新執行 nlm login，確認瀏覽器確實登入成功 | | 瀏覽器沒有自動開啟 | 手動開 <https://notebooklm.google.com/> 確認已登入，或試 nlm login --manual（用 nlm login --help 確認你的版本支援哪些選項） | | 想換另一個 Google 帳號 | nlm login --clear 重新登入；多帳號可用 nlm login switch <profile> | | opencode mcp list 沒有 notebooklm 這一列 | 設定沒寫進去或寫錯層級。確認 mcp 在頂層，不要巢狀在別的項目裡；或直接跑 nlm setup add opencode 讓它幫你寫 | | opencode mcp list 顯示連線失敗 / 逾時 | ①command 是不是誤填成 nlm？要填 notebooklm-mcp ②有沒有加 "timeout": 300000？③跑 opencode mcp debug notebooklm 看細節 | | 設定檔改了但沒反應 | 完全關閉 OpenCode 再重開；仍不行用 opencode mcp list 確認它到底讀到什麼 | | 大工作跑到一半被中斷（產影片、產簡報） | 逾時太短。把 timeout 調大，並補上全域的 experimental.mcp_timeout（見步驟五） | | ModuleNotFoundError: No module named 'notebooklm_tools' | 安裝被弄壞了（多半是手動搬過檔案）。uv tool uninstall notebooklm-mcp-cli 後重裝，不要自己去搬 .local\bin 裡的檔案 | | Windows 上指令格式錯誤 | 使用 PowerShell，不要用 CMD；不要用 && 串指令，用 ; | | nlm list 之類的指令在 Windows 顯示亂碼或 UnicodeDecodeError | 設定 $env:PYTHONIOENCODING = "utf-8" 再跑。這是 Windows 中文版 cp950 編碼的已知問題，不影響 MCP 功能 | | 網頁介面改叫別的名字了 | Google 有在調整 NotebookLM 的品牌與網址。工具會自動處理新舊網域，指令不用改；真的連不上再跑 nlm doctor 看診斷 |

---

相關懶人包

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