<div align="center">

Sumulige NotebookLM MCP 服务器

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

</div>

---

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

一个常见的问题

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

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

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

1. Claude 的知识有截止日期——新出的库、更新的 API，它可能不知道
2. Claude 会"填补空白"——当信息不足时，它会根据经验"猜测"一个看似合理的答案
3. 读取本地文档消耗巨大——让 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 分钟快速上手

<details> <summary><b>前提条件</b>（点击查看）</summary>

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

</details>

步骤 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：创建知识库

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

步骤 4：开始使用

告诉您的 AI：

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

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

---

第四部分：核心概念详解

<details> <summary><b>什么是"零幻觉"？</b></summary>

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

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

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

</details>

<details> <summary><b>为什么需要 MCP？</b></summary>

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

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

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

</details>

<details> <summary><b>自动追问是什么？</b></summary>

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

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

示例：

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

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

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

</details>

---

第五部分：安装指南

系统要求

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

按客户端安装

<details> <summary><b>Claude Code</b></summary>

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

# 验证
claude mcp list

# 卸载
claude mcp remove notebooklm

</details>

<details> <summary><b>Cursor</b></summary>

编辑 ~/.cursor/mcp.json：

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

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

</details>

<details> <summary><b>Codex</b></summary>

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

# 验证
codex mcp list

# 卸载
codex mcp remove notebooklm

</details>

<details> <summary><b>Gemini / VS Code / 其他</b></summary>

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"]
    }
  }
}

</details>

---

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

场景 1：学习新框架

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

操作：

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

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

---

场景 2：查询内部 API 文档

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

操作：

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

结果： 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"	清除并重新认证

---

第七部分：高级配置

<details> <summary><b>工具配置文件（减少 Token 消耗）</b></summary>

通过只加载需要的工具来减少 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

</details>

<details> <summary><b>环境变量配置</b></summary>

浏览器行为：

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

</details>

<details> <summary><b>故障排查</b></summary>

"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

</details>

<details> <summary><b>新架构特性开关</b></summary>

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

</details>

---

第八部分：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

---

常见问题

<details> <summary><b>真的零幻觉吗？</b></summary>

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

<details> <summary><b>有速率限制吗？</b></summary>

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

<details> <summary><b>这有多安全？</b></summary>

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

<details> <summary><b>可以看到正在发生什么吗？</b></summary>

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

---

<div align="center">

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

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

English Version • 报告问题

</div>