Notebooklm MCP

🚀 NotebookLM MCP

NotebookLM MCP 是一款專業的 MCP 服務器，用於實現 Google NotebookLM 的自動化操作。它已發佈到 PyPI，可直接用於生產環境。

✨ 主要特性

• 🔥 FastMCP v2：基於現代裝飾器的 MCP 框架
• ⚡ UV Python 管理器：極速依賴管理
• 🚀 多傳輸協議支持：支持 STDIO、HTTP、SSE
• 🎯 類型安全：完整的 Pydantic 驗證
• 🔒 持久認證：自動管理 Google 會話
• 📊 豐富的命令行界面：藉助 Taskfile 實現自動化，擁有美觀的終端界面
• 🐳 生產就緒：支持 Docker 部署，並提供監控功能

🚀 快速開始

🎯 終端用戶（推薦）

# 安裝 UV（現代 Python 包管理器）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 從 PyPI 安裝 NotebookLM MCP
uv add notebooklm-mcp

# 使用你的 NotebookLM URL 進行初始化
uv run notebooklm-mcp init https://notebooklm.google.com/notebook/YOUR_NOTEBOOK_ID

初始化後會發生什麼：

• ✅ 創建 notebooklm-config.json 文件，保存你的配置信息
• ✅ 創建 chrome_profile_notebooklm/ 文件夾，用於持久認證
• ✅ 打開瀏覽器進行一次性 Google 登錄（如有需要）
• ✅ 保存會話，以便後續無頭操作

# 啟動服務器（為 MCP 客戶端提供 STDIO 服務）
uv run notebooklm-mcp --config notebooklm-config.json server

# 啟動 HTTP 服務器，用於 Web 測試
uv run notebooklm-mcp --config notebooklm-config.json server --transport http --port 8001

# 交互式聊天模式
uv run notebooklm-mcp --config notebooklm-config.json chat  --message "Who are you ?"

👨‍💻 開發者

如果你想為這個項目做貢獻，可以查看我們的 Taskfile，以獲得更好的開發體驗：

git clone https://github.com/khengyun/notebooklm-mcp.git
cd notebooklm-mcp

# 使用開發工具完成設置
task setup

# 顯示所有可用的開發任務
task --list

📦 安裝指南

替代安裝方式

如果你更喜歡使用 pip 而不是 UV，可以按照以下步驟安裝：

# 使用 pip 安裝
pip install notebooklm-mcp

# 初始化
notebooklm-mcp init https://notebooklm.google.com/notebook/YOUR_NOTEBOOK_ID

# 啟動服務器
notebooklm-mcp --config notebooklm-config.json server

📁 初始化後的項目結構

運行 init 命令後，你的工作目錄將包含以下內容：

your-project/
├── notebooklm-config.json          # 配置文件
├── chrome_profile_notebooklm/      # 瀏覽器配置文件（用於持久認證）
│   ├── Default/                    # Chrome 配置文件數據
│   ├── SingletonSocket             # 會話文件
│   └── ...                         # 其他 Chrome 數據
└── your-other-files

關鍵文件說明：

• notebooklm-config.json：包含筆記本 ID、服務器設置、認證配置等信息
• chrome_profile_notebooklm/：存儲 Google 認證會話，支持無頭操作

🛠️ 可用工具

👨‍💻 開發者工作流

對於貢獻者和高級用戶，為了提高生產力，我們提供了一個包含 20 多個自動化任務的綜合 Taskfile：

# 📦 依賴管理
task deps-add -- requests       # 添加依賴
task deps-add-dev -- pytest     # 添加開發依賴
task deps-remove -- requests    # 移除依賴
task deps-list                  # 列出依賴
task deps-update                # 更新所有依賴

# 🧪 測試與質量檢查
task test                       # 運行所有測試
task test-quick                 # 快速驗證測試
task test-coverage              # 覆蓋率分析
task enforce-test               # 函數更改後強制測試
task lint                       # 運行所有代碼檢查
task format                     # 格式化代碼（Black + isort + Ruff）

# 🏗️ 構建與發佈
task build                      # 構建包
task clean                      # 清理構建產物

# 🚀 服務器命令
task server-stdio              # 啟動 STDIO 服務器
task server-http               # 啟動 HTTP 服務器
task server-sse                # 啟動 SSE 服務器

# 顯示所有可用任務
task --list

💡 使用建議：安裝 Task 可獲得最佳開發體驗：go install github.com/go-task/task/v3/cmd/task@latest

🌐 傳輸選項

STDIO（默認）

task server-stdio
# 適用於：LangGraph、CrewAI、AutoGen

HTTP

task server-http  
# 訪問地址：http://localhost:8001/mcp
# 適用於：Web 測試、REST API

SSE

task server-sse
# 訪問地址：http://localhost:8002/
# 適用於：實時流傳輸

💻 使用示例

HTTP 客戶端測試

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(url="http://localhost:8001/mcp")
async with Client(transport) as client:
    tools = await client.list_tools()
    result = await client.call_tool("healthcheck", {})

命令行測試

# 使用 curl 進行測試
curl -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

LangGraph 集成示例

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

# HTTP 傳輸
transport = StreamableHttpTransport(url="http://localhost:8001/mcp")
client = Client(transport)
tools = await client.list_tools()

CrewAI 集成示例

from crewai_tools import BaseTool
from fastmcp import Client

class NotebookLMTool(BaseTool):
    name = "notebooklm"
    description = "Chat with NotebookLM"
    
    async def _arun(self, message: str):
        client = Client("http://localhost:8001/mcp")
        result = await client.call_tool("chat_with_notebook", {"message": message})
        return result

🔒 認證

自動設置

# 首次使用 - 打開瀏覽器進行登錄
notebooklm-mcp init https://notebooklm.google.com/notebook/abc123

# 後續運行 - 使用保存的會話
notebooklm-mcp --config notebooklm-config.json server

手動設置

# 交互式瀏覽器登錄
notebooklm-mcp --config notebooklm-config.json server

# 檢查連接
notebooklm-mcp --config notebooklm-config.json test --notebook YOUR_NOTEBOOK_ID

🐳 Docker 部署

快速開始

# 1. 生成配置文件和 Chrome 配置文件，並引導登錄
uv run notebooklm-mcp init https://notebooklm.google.com/notebook/YOUR_NOTEBOOK_ID
# 如果你使用 pip 安裝，運行：notebooklm-mcp init https://notebooklm.google.com/notebook/YOUR_NOTEBOOK_ID

# 2. 構建容器鏡像
docker build -t notebooklm-mcp .

# 3. 掛載配置文件和配置文件目錄，運行服務器
docker run -d \
  --name notebooklm-mcp \
  --restart unless-stopped \
  -v $(pwd)/notebooklm-config.json:/app/notebooklm-config.json:ro \
  -v $(pwd)/chrome_profile_notebooklm:/app/chrome_profile_notebooklm \
  notebooklm-mcp:latest

使用 Docker Compose

version: '3.8'
services:
  notebooklm-mcp:
    image: notebooklm-mcp:latest
    build: .
    restart: unless-stopped
    volumes:
      - ./notebooklm-config.json:/app/notebooklm-config.json:ro
      - ./chrome_profile_notebooklm:/app/chrome_profile_notebooklm

在運行一次 init 命令，確保 notebooklm-config.json 和 chrome_profile_notebooklm/ 存在後，使用 docker compose up -d 啟動服務。服務器默認以 STDIO 模式運行；如果你的客戶端需要 HTTP/SSE 端口，請在 docker-compose.yml 中取消註釋相應端口。

⚙️ 配置

配置文件 (notebooklm-config.json)

{
  "default_notebook_id": "your-notebook-id",
  "headless": true,
  "timeout": 30,
  "auth": {
    "profile_dir": "./chrome_profile_notebooklm"
  },
  "debug": false
}

環境變量

export NOTEBOOKLM_NOTEBOOK_ID="your-notebook-id"
export NOTEBOOKLM_HEADLESS=true
export NOTEBOOKLM_DEBUG=false

🚀 性能

FastMCP v2 的優勢

• ⚡ 工具註冊速度快 5 倍：使用裝飾器實現
• 📋 自動生成模式：根據 Python 類型提示生成
• 🔒 內置驗證：使用 Pydantic 進行驗證
• 🧪 更好的測試和調試能力
• 📊 全棧類型安全

性能對比

🛠️ 開發

環境搭建

git clone https://github.com/khengyun/notebooklm-mcp
cd notebooklm-mcp

# 使用 UV（推薦）
uv sync --all-groups

# 或者使用 pip
pip install -e ".[dev]"

測試

# 使用 UV 運行測試
uv run pytest

# 測試覆蓋率
uv run pytest --cov=notebooklm_mcp

# 集成測試  
uv run pytest tests/test_integration.py

# 或者使用 Taskfile 進行開發測試
task test
task test-coverage

代碼質量

# 使用 UV 格式化代碼
uv run black src/ tests/
uv run ruff check src/ tests/

# 類型檢查
uv run mypy src/

# 或者使用 Taskfile 快捷命令
task format
task lint

📚 詳細文檔

• 快速設置指南 - 2 分鐘快速上手
• HTTP 服務器指南 - Web 測試與集成
• FastMCP v2 指南 - 現代 MCP 特性
• Docker 部署 - 生產環境部署
• API 參考 - 完整的工具文檔

🔗 相關項目

• FastMCP - 現代 MCP 框架
• MCP 規範 - 官方 MCP 規範
• NotebookLM - Google 的 AI 筆記本

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🆘 支持

• 問題反饋：GitHub Issues
• 討論交流：GitHub Discussions
• 文檔查閱：Read the Docs

本項目由 ❤️ FastMCP v2 構建 - 讓現代 MCP 開發變得簡單！