notebooklm-mcp

NotebookLM（Gemini Notebook）—— CLI + MCP

Google NotebookLM 没有官方 API。notebooklm-mcp-cli 软件包（nlm CLI + notebooklm-mcp 服务）是一个第三方非官方客户端，通过从已登录的 Google 会话中提取浏览器 Cookie并缓存来进行身份验证。本技能介绍两种适合无头环境的身份验证方法，以及 MCP 服务的连接配置。

安全提示：cookies.txt 文件或缓存的 auth.json 等同于 Google 会话。未经用户明确同意，Agent 绝不能提取、读取或转发 Cookie 值。

路径	二进制文件	传输方式	适用场景
A. CLI	nlm	shell	任何可访问 shell 的 Agent。可全面管理笔记本/来源/笔记/聊天/工作室。
B. MCP	notebooklm-mcp	stdio（或 http/sse）	原生支持 MCP 的 Agent（Claude Code、Cursor、Devin、Gemini CLI）。提供约 30 个工具（notebook_create、source_add、chat、audio、report……）。

两种路径共用位于 ~/.notebooklm-mcp-cli/profiles/<profile>/auth.json 的同一 Cookie 缓存。

适用场景

• devin mcp list / claude mcp list 显示 notebooklm-mcp 无法列出工具。

• nlm login --check 返回 ClientAuthenticationError 或 network_error。

• nlm doctor 报告“Browser: not found”（无头服务器）。

• 用户想在没有桌面浏览器的服务器上对 NotebookLM 进行身份验证。

• 用户要求为 Claude Code / Cursor / Devin / Gemini 配置 NotebookLM MCP 服务。

• 用户需要手动提取 Google Cookie，或通过外部 CDP 端点进行身份验证。

• 用户用英语询问或提及此技能（例如：“use /notebooklm-mcp”、“run notebooklm-mcp”）。

• 用户用葡萄牙语询问或提及此技能（例如：“use /notebooklm-mcp”、“execute notebooklm-mcp”）。

不适用场景

• 用户想要通用的“抓取 Google 文档”工具——NotebookLM 专用于 NotebookLM 产品。
• 用户使用的桌面设备已安装 Chrome——只需运行 nlm login（自动模式）；无需使用此技能。

防护措施

• 由用户执行安装：Agent 不会安装或升级 notebooklm-mcp-cli。如果 PATH 中缺少 nlm/notebooklm-mcp，请停止操作，并将下方的安装代码块交给用户——由用户审核并运行。建议明确指定固定版本 ==<VERSION>；绝不可直接安装未指定版本的软件包。
• 用户安装前验证上游信息：在 PyPI 和上游源代码中确认软件包名称和版本。将其视为非官方客户端。
• 所有身份验证方式都必须获得人工确认：在提取 Cookie、导入文件或使用受管浏览器的 CDP 端点之前，Agent 必须先获得用户的明确同意。
• 禁止自动收集 Cookie：绝不可在后台提取 Cookie，也绝不可从用户未明确授权的浏览器中提取 Cookie。
• Cookie 属于凭据：cookies.txt 文件或缓存的 auth.json 等同于 Google 会话。绝不可提交、分享、记录、截屏、复制到剪贴板或传输这些文件。
• 立即删除 Cookie 文件：nlm login --manual --file 成功后，立即删除 cookies.txt。不得将其留在 /tmp、项目目录或任何共享位置。
• 禁止转交凭据：将 nlm login 作为黑盒命令运行。不得读取、解析或转发 cookies.txt 或 auth.json 的内容。
• 优先使用官方身份验证方式：有浏览器可用时，在桌面环境中使用自动模式运行 nlm login。仅在用户控制的无头服务器上使用手动 Cookie 模式。
• 禁止采集浏览器数据：仅从用户自己的浏览器会话中提取 Cookie；提取的 Cookie 只能用于对 nlm 进行身份验证。
• 信任前先验证：执行任何笔记本操作前，先运行 nlm login --check 和 nlm doctor。
• 禁止特权操作：除非用户明确提出并确认原因，否则不得以提升的权限（sudo）或 root 身份运行 nlm。
• 隔离身份验证缓存：可能有多个用户访问环境时，优先使用按项目或按配置文件隔离的身份验证信息，而非共享默认配置文件。
• 披露账户风险：nlm 是非官方客户端，可能违反 Google 服务条款；使用它的账户可能会遭到限流或封禁。应明确说明此风险并建议使用备用或专用的 Google 账户；未作此警告前，绝不可让用户使用其主要账户。
• 会话范围：导入的 Cookie 会授予完整的 Google 网页会话权限，远超 NotebookLM 的范围。请将 auth.json/cookies.txt 视为账户级凭据，而非仅限 NotebookLM 的令牌。
• 数据敏感性：添加到笔记本的所有内容（来源、文件、聊天提示词）都会发送给 Google。绝不可将机密、凭据或个人身份信息（PII）作为来源或提示词；上传内容未经审核的文件前，必须先征得用户同意。
• MCP 传输范围：优先使用 stdio（仅供本地 Agent 使用）。仅在用户明确要求时使用 --transport http/sse；绑定到 localhost，并在向远程开放前配置 TLS + 身份验证反向代理。

---

安装（由用户执行，而非 Agent）

notebooklm-mcp-cli 是第三方 PyPI 发行包。Agent 不得为其运行软件包安装命令——如果缺少 nlm/notebooklm-mcp，请原样提供下方代码块，并等待用户自行运行。

固定到一个已知版本。将 <VERSION> 替换为用户在 PyPI 上验证过的稳定版本（例如通过 pip index versions notebooklm-mcp-cli 查询）。

# Option 1: uv (recommended)
uv tool install notebooklm-mcp-cli==<VERSION>

# Option 2: pipx
pipx install notebooklm-mcp-cli==<VERSION>

# Option 3: pip (only in a virtual environment; avoid --user)
pip install notebooklm-mcp-cli==<VERSION>

验证：

nlm --version          # 0.9.x
which nlm notebooklm-mcp

可随时运行诊断：

nlm doctor             # checks install, auth, browser, AI-tool configs
nlm doctor -v          # verbose

---

身份验证

NotebookLM 没有 API 密钥。支持的身份验证方式是在有浏览器的设备上运行 nlm login。除非用户明确要求使用无头模式备用方案并确认该方法，否则 Agent 不得提取、读取或转发 Google 会话 Cookie。

方法	命令	要求	适用场景
桌面自动登录（首选）	nlm login	桌面或服务器浏览器（Chrome/Chromium/Brave/Edge/Arc/Firefox）	默认方式——只要有浏览器，就优先使用
OpenClaw CDP	nlm login --provider openclaw --cdp-url http://127.0.0.1:18800	已登录 Google 的 OpenClaw 托管浏览器	用户运行 OpenClaw 并确认 CDP 端点时
手动 Cookie 文件	nlm login --manual --file cookies.txt	用户提供的 cookies.txt 文件	用户掌控的无头服务器上的紧急备用方案
桌面自动登录 + 复制 auth.json	在桌面上运行 nlm login，然后复制 ~/.notebooklm-mcp-cli/profiles/<profile>/auth.json	带浏览器的桌面设备	用户明确自行复制缓存的身份验证文件时

无头设备上的备用方案顺序：（1）桌面自动登录，由用户复制 auth.json；（2）使用用户掌控的托管浏览器进行 OpenClaw CDP；（3）仅将手动 Cookie 文件作为紧急备用方案。

桌面自动登录

在装有受支持浏览器的桌面或服务器上：

nlm login              # launches a dedicated browser profile; the user logs in
nlm login --check

指定浏览器：

nlm config set auth.browser chromium   # or brave, arc, edge, chrome, firefox, vivaldi, opera

这是 Agent 应自主运行的唯一身份验证方式。

OpenClaw CDP（需要用户批准）

nlm login --provider openclaw --cdp-url http://127.0.0.1:18800

如果你配置了使用不同 CDP 端口的自定义 OpenClaw 浏览器配置文件：

# Check your OpenClaw browser config
openclaw config get browser.profiles

# Use the matching CDP port
nlm login --provider openclaw --cdp-url http://127.0.0.1:<port>

OpenClaw 浏览器必须已登录 Google / NotebookLM。WebSocket CDP 命令使用 suppress_origin=True，以支持拒绝默认 Origin 标头的托管端点。

方法 1 — 手动 Cookie 文件（仅限紧急备用方案）

Agent 不得自动执行这些步骤。 手动提取 Cookie 是用户掌控的无头服务器上的紧急备用方案。用户必须自行创建 cookies.txt，并在导入后立即删除。

步骤 1：用户在装有 Chrome 的设备上提取 Cookie

1. 打开 Chrome 并访问 https://notebooklm.google.com
2. 确保已登录 Google 账号。
3. 按 F12（或在 Mac 上按 Cmd+Option+I）打开 DevTools。
4. 点击 Network 标签页。
5. 在筛选框中输入：batchexecute
6. 点击任意笔记本以触发请求。
7. 点击列表中的某个 batchexecute 请求。
8. 在右侧面板中，滚动到 Request Headers。
9. 找到以 cookie: 开头的行。
10. 右键点击 Cookie 值，然后选择 Copy value。
11. 将其粘贴到文本文件中，并保存为 cookies.txt。

Cookie 文件格式

该文件应包含从 Chrome DevTools 获取的原始 Cookie 字符串：

SID=abc123...; HSID=xyz789...; SSID=...; APISID=...; SAPISID=...; __Secure-1PSID=...; __Secure-3PSID=...; ...

• 以 # 开头的行会被视为注释并忽略。
• Cookie 字符串可以放在一行或多行中。

步骤 2：在服务器上导入

# The user copies cookies.txt to the server, then:
nlm login --manual --file cookies.txt

# Delete the cookie file immediately after successful import
shred -u cookies.txt 2>/dev/null || rm -f cookies.txt

步骤 3：验证

nlm login --check
# ✓ Authenticated as [email protected]

nlm doctor
# Authentication: cookies present, CSRF token: yes, account: [email protected]

令牌会缓存在 ~/.notebooklm-mcp-cli/profiles/default/auth.json。

方法 2 — OpenClaw CDP 提供程序

如果 OpenClaw 托管的浏览器已在运行并公开了 Chrome DevTools Protocol 端点，nlm 可以直接从中读取 Cookie，而无需启动第二个浏览器：

nlm login --provider openclaw --cdp-url http://127.0.0.1:18800

• WebSocket CDP 命令使用 suppress_origin=True，以支持拒绝默认 Origin 标头的托管端点。
• 浏览器必须已登录 Google / NotebookLM。
• 如果端点响应较慢，请增加 DevTools 超时：nlm login --provider openclaw --cdp-url http://127.0.0.1:18800 --devtools-timeout 15

按相同方式验证：

nlm login --check

方法 3 — 自动模式（带浏览器的桌面设备）

在安装了 Chrome/Chromium/Brave/Edge/Arc/Firefox 的桌面设备上：

nlm login              # launches a dedicated browser profile, you log in, cookies extracted

指定浏览器：

nlm config set auth.browser chromium   # or brave, arc, edge, chrome, firefox, vivaldi, opera

多配置文件认证

支持通过命名配置文件使用多个 Google 账号：

nlm login --profile work
nlm login --profile personal
nlm login switch work
nlm login profile list
nlm login profile delete personal

MCP 服务始终使用当前活动的默认配置文件。切换默认配置文件会立即切换 MCP 服务使用的 Google 账号：

nlm login switch personal
nlm config set auth.default_profile personal

认证生命周期

组件	时长	刷新方式
Cookies	约 2-4 周	通过无头浏览器自动刷新（如果已保存配置文件）
CSRF 令牌	几分钟	每次请求失败时自动刷新
Session ID	会话期间	嵌入 cookies 中

Cookies 过期时：

nlm login --check        # reports stale/unverified
nlm login                # re-extract (auto mode)
nlm login --manual --file cookies.txt   # re-extract (manual mode)

认证安全检查清单

执行任何认证操作前，请确认以下所有事项。如果有任何事项不明确，请停止并询问用户。

• 用户明确请求使用此认证方式，并了解其中涉及 Google 会话 cookies。
• 目标机器由用户控制（个人工作站或其管理的服务器）。
• 不会提交或记录任何 cookie 文件，不会将其复制到剪贴板，也不会在导入后留存在磁盘上。
• 如果使用 --provider openclaw，CDP 端点属于用户自己的 OpenClaw 管理的浏览器。
• 如果使用 --manual --file cookies.txt，该文件由用户提供，且用户会在导入后将其删除。
• 在执行任何 notebook 操作前，nlm login --check 和 nlm doctor 均通过。

---

路径 A — CLI 用法

# Notebooks
nlm notebook list
nlm notebook create --title "My Notebook"
nlm notebook get <notebook_id>
nlm notebook delete <notebook_id>

# Sources
nlm source add <notebook_id> --url https://example.com/doc
nlm source add <notebook_id> --file ./paper.pdf
nlm source list <notebook_id>

# Notes
nlm note add <notebook_id> --text "My note"
nlm note list <notebook_id>

# Chat
nlm chats start <notebook_id>
nlm chats send <notebook_id> "Summarize the sources"

# Audio overviews
nlm audio create <notebook_id>
nlm download <notebook_id> --artifact audio

# Reports
nlm report create <notebook_id> --topic "Key findings"

# Research
nlm research discover "climate adaptation strategies"

# Batch + cross-notebook
nlm batch <notebook_ids_file> --command "summarize"
nlm cross query "find mentions of X across all notebooks"

# Tags + labels
nlm tag add <notebook_id> research
nlm label add <notebook_id> source_1 priority

# Sharing + export
nlm share <notebook_id> --email [email protected]
nlm export <notebook_id> --format docs

# Diagnostics
nlm doctor
nlm doctor auth-replay     # diagnose cookie replay vs browser-bound auth failures

---

路径 B — MCP 服务

B.1 配置

最简单的方法是使用 nlm setup（支持 Claude Code、Claude Desktop、Cursor、Gemini CLI、GitHub Copilot、Windsurf）：

nlm setup add claude-code       # Claude Code
nlm setup add claude-desktop    # Claude Desktop
nlm setup add gemini            # Gemini CLI / Antigravity IDE
nlm setup add github-copilot    # GitHub Copilot
nlm setup add cursor            # Cursor
nlm setup add windsurf          # Windsurf
nlm setup add json              # Any other tool (interactive JSON generator)

nlm setup list                  # show supported tools + their MCP config status

对于 nlm setup 未涵盖的平台（Devin CLI/Desktop、OpenCode、Antigravity CLI、OpenClaw），请使用附带的设置脚本或手动编辑配置。

各平台配置 — 关键注意事项

每个 MCP 客户端平台都有自己的配置格式。字段名称填写错误会导致服务被静默忽略（没有错误提示，只是没有工具）。完整对照表请参见 references/platform-quirks.md。

平台	配置文件	根键	Stdio 命令	注意事项
Claude Code	~/.claude.json	mcpServers	command + args	type: "stdio"
Claude Desktop	claude_desktop_config.json	mcpServers	command + args	—
Cursor	~/.cursor/mcp.json	mcpServers	command + args	必须设置 type: "stdio"
Devin CLI	~/.config/devin/mcp_config.json	mcpServers	command + args	devin mcp add CLI
Devin Desktop	~/.devin/mcp_config.json	mcpServers	command + args	—
OpenCode	~/.config/opencode/opencode.json	mcp	command（单个数组）	type: "local"，使用 environment 而非 env
Antigravity IDE/CLI	~/.gemini/config/mcp_config.json	mcpServers	command + args	卸载时清除缓存
OpenClaw	OpenClaw 配置	mcp.servers	command + args	openclaw mcp add CLI

最常见的 3 个静默失败陷阱：

1. OpenCode 使用 mcp（而非 mcpServers）、environment（而非 env），且 command 是单个数组（将二进制文件和参数合并）。
2. OpenClaw 使用 mcp.servers（带点号），并设置 transport: "stdio"，通过 openclaw mcp add/set 管理。
3. Antigravity 会将 MCP 服务缓存到 ~/.gemini/antigravity{,-ide,-cli}/mcp/ — 卸载时必须删除缓存目录。

各平台对应的确切 JSON 配置块请参见 references/mcp-config.md。

自动化设置助手

运行附带的助手，以检测所有已安装的平台，并按正确格式修改各平台配置：

bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh
# dry-run:
bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh --dry-run
# target one platform:
bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh --platform cursor
# use bare notebooklm-mcp binary instead of nlm wrapper:
bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh --binary notebooklm-mcp
# remove:
bash skills/notebooklm-mcp/scripts/setup_notebooklm_mcp.sh --remove

传输选项

notebooklm-mcp                          # stdio (default, for local agents)
notebooklm-mcp --transport http --port 8000   # HTTP (for remote agents)
notebooklm-mcp --transport sse  --port 8000   # SSE

环境变量：

变量	描述
NOTEBOOKLM_MCP_TRANSPORT	传输类型（stdio/http/sse）
NOTEBOOKLM_MCP_PORT	HTTP/SSE 端口
NOTEBOOKLM_MCP_DEBUG	启用详细日志记录
NOTEBOOKLM_HL	界面语言／区域设置（例如 pt-BR、es-419）
NOTEBOOKLM_QUERY_TIMEOUT	查询超时时间（秒）
NOTEBOOKLM_BASE_URL	覆盖 Enterprise/Workspace 的基本 URL

远程 MCP 警告： HTTP 传输不提供 HTTPS、调用方身份验证、按用户区分的 NotebookLM 账户或远程文件传输。除非使用反向代理添加 TLS 和身份验证，否则请勿将其公开。

B.2 验证

完成配置后，重启 Agent。MCP 服务会提供约 30 个工具。请在 Agent 中检查：

mcp_list_tools("notebooklm-mcp")
# Expect: notebook_create, notebook_list, source_add, source_list, chat_send,
#         audio_create, report_create, refresh_auth, save_auth_tokens, ...

在 Shell 中：

bash skills/notebooklm-mcp/scripts/verify_notebooklm.sh

B.3 通过 MCP 提供的身份验证工具

工具	描述
refresh_auth	从缓存的配置文件重新加载身份验证令牌
save_auth_tokens	保存 Cookie（备用方法）

如果 MCP 工具调用因身份验证错误而失败，请先调用 refresh_auth。如果仍然失败，请在主机上重新运行 nlm login。

---

无头身份验证流程（决策图）

┌────────────────────────────────────────────────────────────────┐
│ Is an OpenClaw browser running with CDP on 127.0.0.1:18800?    │
│   YES → nlm login --provider openclaw --cdp-url http://...     │
│   NO  ↓                                                        │
│ Do you have a cookies.txt file (extracted on another machine)? │
│   YES → nlm login --manual --file cookies.txt                  │
│   NO  ↓                                                        │
│ Can you run nlm login on a desktop with Chrome?                │
│   YES → nlm login (auto mode) → copy auth.json to the server   │
│         (cp ~/.notebooklm-mcp-cli/profiles/default/auth.json   │
│            server:~/.notebooklm-mcp-cli/profiles/default/)     │
│   NO  → cannot authenticate; NotebookLM needs Google cookies   │
└────────────────────────────────────────────────────────────────┘

---

故障排除

症状	原因	修复方法
nlm login --check → ClientAuthenticationError	Cookie 已过期或无效	重新提取：nlm login --manual --file cookies.txt 或 nlm login
nlm doctor → "Browser: not found"	无头服务器上没有 Chrome	使用手动文件模式或 OpenClaw CDP（参见身份验证部分）
nlm doctor → "Headless auth: not available"	没有已保存的浏览器配置文件	在桌面设备上运行一次 nlm login 以保存配置文件，或使用手动模式
MCP 工具因身份验证错误而失败	缓存的 Cookie 已过期	调用 refresh_auth MCP 工具，或在主机上运行 nlm login
--check 出现 network_error	Cookie 存在，但会话已失效	重新登录；已保存的凭据可能仍然有效，但会话已过期
配置了两个 Gemini Notebook 服务	工具名称重叠导致 Agent 混淆	移除旧版服务；仅保留 notebooklm-mcp
nlm setup add <tool> 提示 "already configured"	已存在配置项	先运行 nlm setup remove <tool> 再重新添加，或手动编辑配置
Cookie 重放失败（绑定浏览器的身份验证）	Google 要求使用绑定浏览器的会话	运行 nlm doctor auth-replay 进行诊断；可能需要使用真实浏览器运行自动模式

---

参考资料

• references/mcp-config.md — 各平台完整的 JSON 配置块（Claude Code/Desktop、Cursor、Devin CLI/Desktop、OpenCode、Antigravity IDE/CLI、OpenClaw）。
• references/platform-quirks.md — 跨平台 MCP 配置差异对照表（serverUrl 与 url、mcp 与 mcpServers、environment 与 env、环境变量替换语法、OpenClaw CDP 端口）。
• references/auth-guide.md — 深入介绍 Cookie 提取、文件格式、多配置文件、OpenClaw CDP 和身份验证生命周期。
• scripts/setup_notebooklm_mcp.sh — 检测所有已安装的平台，并按正确格式为每个平台修补配置（处理 mcp/mcpServers、命令数组、environment/env、OpenClaw CLI）。
• scripts/verify_notebooklm.sh — 运行 nlm doctor + nlm login --check + 列出笔记本，确认端到端流程正常。
• scripts/extract_cookies_help.sh — 向用户打印逐步 Cookie 提取说明。
• 身份验证指南（上游）
• MCP 指南（上游）
• CLI 指南（上游）
• PyPI
• Devin CLI MCP 配置
• Antigravity MCP 文档
• OpenCode MCP 服务
• OpenClaw MCP 工具
• OpenClaw 浏览器 CDP
• Cursor MCP 文档