sumulige-notebooklm-mcp

Sumulige NotebookLM MCP 服务器

让您的 AI 代理直接与 NotebookLM 对话，获得基于您文档的准确答案

第一部分：这是什么？为什么要用它？

一个常见的问题

你有没有遇到过这种情况：

你让 Claude 帮你写代码，使用某个库的 API。结果它自信地写了一段代码，但运行时却报错——这个 API 根本不存在。

这不是 Claude 故意捣乱。问题是：

• Claude 的知识有截止日期——新出的库、更新的 API，它可能不知道
• Claude 会"填补空白"——当信息不足时，它会根据经验"猜测"一个看似合理的答案
• 读取本地文档消耗巨大——让 AI 搜索多个文件需要消耗大量 token

解决方案

NotebookLM 是 Google 基于 Gemini 2.0 构建的"零幻觉"知识库：

• 你上传文档（PDF、网页、YouTube 视频等）
• NotebookLM 阅读并理解这些内容
• 当你提问时，它只基于你上传的文档回答——不知道的会直接说不知道

NotebookLM MCP 是一座桥梁，让您的 AI 代理（Claude Code、Cursor 等）能够直接向 NotebookLM 提问。

第二部分：它是如何工作的？

一个类比

想象一下：

传统方式：
你 → 把文档发给 Claude → Claude 尝试记住 → 可能编造 API

使用 NotebookLM MCP：
你 → Claude 向"图书管理员"提问 → "图书管理员"查阅文档 → 返回准确答案

NotebookLM 就是那个读透了所有文档的"图书管理员"，而且它拒绝瞎猜。

工作流程

graph LR
    A[你: 帮我用这个库] --> B[Claude Code]
    B --> C[MCP: 我需要查文档]
    C --> D[NotebookLM]
    D --> E[Gemini 阅读你的文档]
    E --> D
    D --> C
    C --> B
    B --> F[准确代码]

核心优势

特性	传统方式	NotebookLM MCP
幻觉风险	高 - 可能编造 API	零 - 只回答文档中的内容
Token 消耗	高 - 需要反复读取文件	低 - 只传输问答结果
知识新鲜度	受限于训练截止	永远最新 - 你上传的就是最新的
多文档关联	困难	简单 - 自动综合多个来源

第三部分：5 分钟快速上手

前提条件（点击查看）

• Node.js 18+ 已安装
• Claude Code / Cursor / Codex 任一工具
• Google 账户（用于使用 NotebookLM）

步骤 1：安装（一行命令）

Claude Code:

claude mcp add notebooklm npx sumulige-notebooklm-mcp@latest

Cursor: 编辑 ~/.cursor/mcp.json，添加：

{
  "mcpServers": {
    "notebooklm": {
      "command": "npx",
      "args": ["-y", "sumulige-notebooklm-mcp@latest"]
    }
  }
}

步骤 2：登录 NotebookLM（一次性）

对您的 AI 说：

"Log me in to NotebookLM"

Chrome 会自动打开，使用 Google 登录即可。

步骤 3：创建知识库

• 访问 notebooklm.google.com
• 创建笔记本，上传您的文档
• 点击 ⚙️ Share → Anyone with link → 复制链接

步骤 4：开始使用

告诉您的 AI：

"I'm working with [库名]。这是我的 NotebookLM：[粘贴链接]"

就这样！ 现在当您提问时，AI 会自动向 NotebookLM 查询文档中的准确信息。

第四部分：核心概念详解

什么是"零幻觉"？

NotebookLM 的设计原则是：严格基于提供的来源回答。

• 如果文档中有答案 → 准确引用并回答
• 如果文档中没有答案 → 直接说"文档中没有提到这个信息"

这与通用大语言模型不同——通用模型倾向于" helpful"，即使不知道也会尝试推测一个答案。

为什么需要 MCP？

MCP（Model Context Protocol） 是 AI 代理使用外部工具的标准方式。

可以把它理解为 AI 的"USB 接口"：

• AI 本身不能直接访问互联网
• 但通过 MCP，AI 可以调用各种"工具"（如浏览器、数据库）
• NotebookLM MCP 就是这样一个工具，让 AI 能够查询 NotebookLM

自动追问是什么？

这是最强大的功能之一。当您问一个复杂问题时，AI 会：

• 先问 NotebookLM 一个基础问题
• 根据答案，提出更深入的追问
• 重复这个过程，直到完全理解

示例：

你: "怎么用这个状态管理库？"

AI → NotebookLM: "这个库的核心概念是什么？"
    → 得到答案后 →
    → NotebookLM: "怎么初始化 store？"
    → 得到答案后 →
    → NotebookLM: "如何处理异步 action？"

最终: AI 综合所有答案，写出准确的代码

第五部分：安装指南

系统要求

要求	最低	推荐
Node.js	18.0.0	20.x LTS
内存	2 GB	4 GB
磁盘空间	500 MB	1 GB

按客户端安装

Claude Code

# 安装
claude mcp add notebooklm npx sumulige-notebooklm-mcp@latest

# 验证
claude mcp list

# 卸载
claude mcp remove notebooklm

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "notebooklm": {
      "command": "npx",
      "args": ["-y", "sumulige-notebooklm-mcp@latest"]
    }
  }
}

注意： 修改后需要重启 Cursor。

Codex

# 安装
codex mcp add notebooklm -- npx sumulige-notebooklm-mcp@latest

# 验证
codex mcp list

# 卸载
codex mcp remove notebooklm

Gemini / VS Code / 其他

Gemini:

gemini mcp add notebooklm npx sumulige-notebooklm-mcp@latest

VS Code:

code --add-mcp '{"name":"notebooklm","command":"npx","args":["sumulige-notebooklm-mcp@latest"]}'

通用配置格式:

{
  "mcpServers": {
    "notebooklm": {
      "command": "npx",
      "args": ["sumulige-notebooklm-mcp@latest"]
    }
  }
}

第六部分：使用场景和示例

场景 1：学习新框架

问题： 你想用一个新的 UI 框架，但不知道 API

操作：

"我要用 [框架名] 构建应用。这是文档 NotebookLM：[链接]"
"这个框架的组件系统是怎么工作的？"
"给我一个完整的组件示例"

结果： AI 基于文档给你准确的代码，不会编造不存在的 API。

场景 2：查询内部 API 文档

问题： 公司的内部 API 文档很复杂

操作：

• 把内部文档上传到 NotebookLM
• 告诉 AI 链接
• 提问："我们的用户认证流程是怎样的？"

结果： AI 准确引用内部文档，给出正确的 API 调用方式。

场景 3：综合多源信息

问题： 信息分散在多个文档、视频、网页中

操作：

• 在 NotebookLM 中创建笔记本
• 添加多个来源（PDF、网站、YouTube 视频等）
• 让 AI 综合回答

结果： NotebookLM 关联所有来源，给出综合性答案。

常用指令速查

意图	对 AI 说	结果
认证	"Log me in to NotebookLM"	打开登录窗口
添加笔记本	"Add [link] to library"	保存笔记本
列出笔记本	"Show our notebooks"	显示所有保存的笔记本
选择笔记本	"Use the React notebook"	设置活动笔记本
查看浏览器	"Show me the browser"	实时查看 NotebookLM 对话
修复认证	"Repair NotebookLM authentication"	清除并重新认证

第七部分：高级配置

工具配置文件（减少 Token 消耗）

通过只加载需要的工具来减少 Token 使用：

配置	工具数	包含工具
minimal	5	仅查询：ask_question, get_health, list_notebooks, select_notebook, get_notebook
standard	10	+ 库管理：setup_auth, list_sessions, add_notebook, update_notebook, search_notebooks
full	16	所有工具

配置方式：

# 环境变量
export NOTEBOOKLM_PROFILE=minimal

# CLI
npx sumulige-notebooklm-mcp@latest --profile minimal

环境变量配置

浏览器行为：

export HEADLESS=false          # 显示浏览器窗口
export BROWSER_TIMEOUT=60000   # 超时时间（毫秒）

隐身模式（模拟人类行为）：

export STEALTH_ENABLED=true
export STEALTH_HUMAN_TYPING=true
export TYPING_WPM_MIN=160      # 打字速度范围
export TYPING_WPM_MAX=240

会话管理：

export MAX_SESSIONS=10         # 最大并发会话
export SESSION_TIMEOUT=900     # 会话超时（秒）

完整配置说明见：docs/configuration.md

故障排查

"Chrome not found"

• Linux: sudo apt install chromium-browser
• macOS/Windows: Chrome 会自动安装

"ProcessSingleton error"

• 关闭所有 Chrome 窗口后重试
• 或设置 NOTEBOOK_PROFILE_STRATEGY=isolated

"Session expired"

• 运行："Re-authenticate with NotebookLM"

更多问题解决方案：docs/troubleshooting.md

新架构特性开关

v1.2.1 引入了六边形架构重构，通过特性开关可启用新组件：

环境变量	描述	默认
FF_USE_NEW_ARCHITECTURE	启用所有新架构组件	false
FF_USE_EVENT_BUS	事件总线（松耦合）	false
FF_USE_AUTH_STATE_MACHINE	认证状态机	false
FF_USE_SESSION_ACTOR	Actor 模型（顺序消息处理）	false
FF_USE_RESPONSE_OBSERVER	MutationObserver（替代轮询）	false

启用全部新特性：

FF_USE_NEW_ARCHITECTURE=true npx sumulige-notebooklm-mcp@latest

逐个启用：

FF_USE_SESSION_ACTOR=true FF_USE_RESPONSE_OBSERVER=true npx sumulige-notebooklm-mcp@latest

第八部分：HTTP API（可选）

除了 MCP 协议，NotebookLM MCP 还提供 REST API 接口，可用于：

• Web 应用集成
• 自定义客户端开发
• 微服务架构
• 自动化脚本

启动 HTTP 服务器

import { ToolHandlers } from "sumulige-notebooklm-mcp";
import { createHttpAdapter } from "sumulige-notebooklm-mcp/adapters";

const adapter = createHttpAdapter(toolHandlers, {
  port: 3000,
  prefix: "/api/v1",
  cors: { origin: true }
});

await adapter.start();
// 服务器运行在 http://localhost:3000

API 端点一览

方法	端点	描述
GET	/health	健康检查
POST	/api/v1/ask	向 NotebookLM 提问
GET	/api/v1/sessions	列出所有会话
DELETE	/api/v1/sessions/:id	关闭会话
POST	/api/v1/sessions/:id/reset	重置会话
GET	/api/v1/notebooks	列出笔记本库
POST	/api/v1/notebooks	添加笔记本
GET	/api/v1/notebooks/:id	获取笔记本详情
PUT	/api/v1/notebooks/:id	更新笔记本
DELETE	/api/v1/notebooks/:id	删除笔记本
POST	/api/v1/notebooks/:id/select	设为活动笔记本
GET	/api/v1/library/stats	获取库统计
POST	/api/v1/auth/setup	设置认证
POST	/api/v1/auth/reauth	重新认证
POST	/api/v1/cleanup	清理数据

使用示例

提问：

curl -X POST http://localhost:3000/api/v1/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "这个库怎么初始化？"}'

流式进度（SSE）：

curl -X POST http://localhost:3000/api/v1/ask \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"question": "详细解释认证流程"}'

列出笔记本：

curl http://localhost:3000/api/v1/notebooks

配置选项

interface HttpAdapterConfig {
  port: number;           // 监听端口
  host?: string;          // 主机地址，默认 "0.0.0.0"
  prefix?: string;        // API 前缀，默认 "/api/v1"
  cors?: {
    origin?: string | string[] | boolean;  // CORS 来源
    credentials?: boolean;                  // 允许凭据
  };
}

流式响应（Streaming）

v1.2.2 新增流式响应功能，实现类似 ChatGPT 的逐字输出体验。

特性：

• 🌊 逐字输出 - 响应文本实时流式返回
• 🔒 安全措施 - 内置间隔和随机抖动，模拟人类行为
• ⚙️ 可配置 - 支持自定义块大小、间隔时间

使用方式：

// 通过 handleAskQuestion 启用流式
const result = await handlers.handleAskQuestion({
  question: "这个库怎么使用？",
  streaming: true,
  streaming_options: {
    min_interval_ms: 100,  // 最小发送间隔
    max_jitter_ms: 50,     // 随机抖动范围
    chunk_size: 0          // 0 = 逐字，>0 = 按块
  }
}, sendProgress, (chunk, fullText) => {
  // 每收到新内容时调用
  process.stdout.write(chunk);
});

// 或直接使用 session
const result = await session.askWithStreaming(
  "解释认证流程",
  (chunk, fullText) => console.log(chunk),
  { minIntervalMs: 100 }
);

流式选项：

选项	类型	默认值	描述
min_interval_ms	number	100	两次发送之间的最小间隔（毫秒）
max_jitter_ms	number	50	随机抖动范围（毫秒）
chunk_size	number	0	块大小（0 = 逐字符，>0 = 按指定字符数）

返回结果：

interface StreamingResult {
  success: boolean;
  response?: string;      // 完整响应文本
  error?: string;
  durationMs: number;     // 总耗时
  totalChars?: number;    // 总字符数
  chunkCount?: number;    // 发送的块数
}

安全说明：

• 内置最小 100ms 间隔防止请求过于频繁
• 随机抖动模拟人类行为，降低被检测风险
• 逐字模式下每字符 10-30ms 随机延迟

第九部分：更多文档

文档	描述	链接
安装指南	详细安装步骤、系统要求、验证方法、卸载和升级	docs/installation.md
使用指南	高级用法、工作流、最佳实践、模式	docs/usage-guide.md
工具参考	完整 MCP 工具 API 文档、参数说明	docs/tools.md
配置说明	环境变量、运行时配置、工具配置	docs/configuration.md
HTTP API	REST API 端点和使用说明	README.md#第八部分http-api可选
流式响应	逐字输出、配置选项、安全措施	README.md#流式响应streaming
问题排查	常见问题和解决方案	docs/troubleshooting.md

常见问题

真的零幻觉吗？

是的。NotebookLM 专门设计为仅从上传的来源回答。如果不知道，它会直接说不知道。

有速率限制吗？

免费 tier 每个账户每天有查询次数限制。支持快速切换账户继续研究。

这有多安全？

Chrome 在本地运行。您的凭据永远不会离开您的机器。如果担心，可以使用专用的 Google 账户。

可以看到正在发生什么吗？

可以！对 AI 说 "Show me the browser" 来实时观看 NotebookLM 对话。

Built with frustration about hallucinated APIs, powered by Google's NotebookLM

⭐ 在 GitHub 上 Star 如果这能节省您的调试时间！

English Version • 报告问题