AI导哈

NotebookLM元数据管理服务

NotebookLM元数据管理服务是一个用于NotebookLM的混合元数据管理服务器，支持元数据操作、笔记本操作、源操作等功能。

  • by brock-run
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 brock-run/notebooklm-mcp

使用说明

NotebookLM MCP服务器

用于NotebookLM的MCP服务器，具有混合元数据强制执行功能（API名称字段+Google Docs自定义属性+本地JSON存储）。

特性

  • ✅ 元数据操作：验证、获取、设置和查询自定义元数据
  • ✅ 笔记本操作：列出、获取、创建、删除和共享笔记本（通过NotebookLM API）
  • ✅ 源操作：添加、获取和删除源（谷歌文档、PDF、网址等）
  • ✅ 音频概述：生成和删除音频概述
  • ✅ 混合存储：三层元数据存储（API字段、Google文档、本地JSON）
  • ✅ OAuth2身份验证：具有自动刷新功能的安全身份验证
  • ✅ 缓存：30秒TTL以获得最佳性能
  • ✅ 测试驱动开发：89多项全面覆盖的测试

建筑

MCP Server
    ↓
Metadata Manager (Orchestrator)
    ↓ ↓ ↓
[NotebookLM API] [Google Docs API] [Local JSON Store]

先决条件

  • Node.js 18+
  • 谷歌云项目：
    • NotebookLM Enterprise API已启用
    • 已启用Google Docs API
    • 已启用Google Drive API
  • OAuth2凭据（客户端ID和机密）

安装

# Clone or copy to your machine
cd /path/to/notebooklm-mcp

# Install dependencies
npm install

# Build
npm run build

配置

1.设置OAuth2凭据

设置环境变量：

export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"

或创建 .env 文件：

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

2.身份验证（第一次）

运行安装流程：

npm run setup  # TODO: Implement OAuth web flow in future

这将：

  1. 打开浏览器进入Google OAuth同意屏幕
  2. 请求NotebookLM、Google Docs和Drive的权限
  3. 将凭据保存到 ~/.notebooklm-mcp/credentials.json

手动测试

在生产环境中使用MCP服务器之前，我们建议遵循手动测试指南来验证一切是否正常工作。

👉 完整的手动测试指南

指南将引导您完成以下操作：

  • 第一阶段： 无身份验证元数据验证（5-10分钟）
  • 第二阶段： OAuth设置和Claude代码集成（10-15分钟）
  • 第三阶段： 端到端工作流测试（15-20分钟）

快速测试 （安装后）：

# Build the server
npm run build

# Run automated tests
npm test

# Expected: 89 tests passing (10 test suites)

有关包括OAuth和Claude Code集成在内的详细测试，请参阅 手动测试指南.

用法

启动MCP服务器

npm start

服务器在stdio上运行，可以与Claude Code一起使用。

在Claude代码中配置

添加到您的Claude Code MCP配置中：

桌面： ~/.claude/desktop-config.json

{
  "mcpServers": {
    "notebooklm": {
      "command": "/path/to/notebooklm-mcp/bin/notebooklm-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

可用的MCP工具

元数据操作

  • notebooklm_validate_metadata -根据架构验证元数据
  • notebooklm_get_metadata -获取笔记本/源的元数据
  • notebooklm_set_metadata -设置元数据
  • notebooklm_query_metadata -按元数据过滤器查询

笔记本操作

  • notebooklm_list_notebooks -列出最近查看的笔记本
  • notebooklm_get_notebook -通过来源获取笔记本详细信息
  • notebooklm_create_notebook -创建新笔记本
  • notebooklm_delete_notebook -删除笔记本
  • notebooklm_share_notebook -与用户共享笔记本

源操作

  • notebooklm_add_sources -将源添加到笔记本
  • notebooklm_get_source -获取源详细信息
  • notebooklm_remove_sources -删除源

音频概述操作

  • notebooklm_generate_audio -生成音频概述
  • notebooklm_delete_audio -删除音频概述

元数据架构（v1.0）

必填字段

{
  type: "notebook-source"  // Fixed value
  project: string          // Project name
  status: "active" | "archived" | "reference" | "in-progress"
}

可选字段

{
  area?: string           // PARA area (e.g., "vocation/spreetail")
  tags?: string[]         // Custom tags
  created?: string        // ISO date (YYYY-MM-DD)
  modified?: string       // ISO date (YYYY-MM-DD)
  customFields?: object   // Extensible custom metadata
}

示例

{
  "type": "notebook-source",
  "project": "palomino-nas",
  "status": "active",
  "area": "vocation/spreetail",
  "tags": ["infrastructure", "backup"],
  "created": "2026-02-17",
  "modified": "2026-02-17",
  "customFields": {
    "priority": "high",
    "owner": "brockbutler"
  }
}

发展

运行测试

make test
# or
npm test

观看模式（TDD）

make test-watch
# or
npm run test:watch

覆盖范围报告

make test-coverage

构建

make build
# or
npm run build

项目结构

/Users/brockstudio/Projects/notebooklm-mcp/
├── src/
│   ├── index.ts                    # Entry point
│   ├── server.ts                   # MCP server with 14 tools
│   ├── config.ts                   # Configuration
│   ├── validators/
│   │   └── schema.ts               # Metadata validation
│   ├── storage/
│   │   └── metadata-store.ts       # Local JSON store
│   ├── cache/
│   │   └── manager.ts              # TTL cache
│   ├── auth/
│   │   └── oauth.ts                # OAuth2 manager
│   ├── clients/
│   │   ├── notebooklm.ts          # NotebookLM API client
│   │   └── google-docs.ts         # Google Docs API client
│   └── managers/
│       └── metadata.ts             # Metadata orchestrator
├── tests/
│   ├── unit/                       # Unit tests
│   ├── integration/                # Integration tests
│   └── setup.ts                    # Test setup
├── bin/
│   └── notebooklm-mcp              # Executable wrapper
├── dist/                           # Compiled JavaScript
├── package.json
├── tsconfig.json
├── jest.config.js
├── Makefile
└── README.md

运行时文件

~/.notebooklm-mcp/
├── credentials.json                # OAuth tokens (chmod 600)
├── metadata.json                   # Local metadata store
└── metadata.json.backup            # Backup (on corruption)

实施状态

✅ 已完成（任务1-14）

  • 项目脚手架及配置
  • 具有模式强制的元数据验证器
  • 具有原子写入的本地JSON存储
  • 带TTL的缓存管理器
  • OAuth2凭据存储和令牌刷新
  • Google Docs API客户端（存根）
  • NotebookLM API客户端（存根）
  • 元数据管理器编排层
  • 配备14个工具的MCP服务器
  • 综合测试（89+次测试）
  • 集成和端到端测试

🔲 未来增强功能（MVP后）

  • OAuth2 web流设置向导
  • 真正的谷歌文档API集成
  • Real NotebookLM API集成
  • 高级查询（全文搜索）
  • 多设备元数据同步
  • 元数据的云备份

故障排除

“找不到凭据”

运行安装流程以向Google进行身份验证：

npm run setup  # TODO: Implement OAuth web flow

“令牌刷新失败”

您的刷新令牌可能已过期。重新运行安装程序：

rm ~/.notebooklm-mcp/credentials.json
npm run setup

“尚未实现NotebookLM API”

NotebookLM API操作当前为存根。它们将在未来阶段通过真正的API集成来实现。

贡献

本项目遵循TDD原则。所有新功能都需要测试。

许可证

麻省理工学院

设计文件

  • 建筑: /Users/brockstudio/Projects/palomino-nas/docs/plans/2026-02-16-notebooklm-api-redesign.md
  • 实施计划: /Users/brockstudio/Projects/palomino-nas/docs/plans/2026-02-16-notebooklm-api-implementation.md

相关 MCP