NotebookLM MCP Server

Instructions

Implementation Reference

• src/tools/handlers.ts:790-882 (handler)

  The primary handler function that executes the cleanup_data tool. It handles both preview (confirm=false) and deletion (confirm=true) modes, instantiates CleanupManager, logs progress, and returns structured ToolResult with preview data or deletion results.
  /** * Handle cleanup_data tool * * ULTRATHINK Deep Cleanup - scans entire system for ALL NotebookLM MCP files */ async handleCleanupData( args: { confirm: boolean; preserve_library?: boolean } ): Promise< ToolResult<{ status: string; mode: string; preview?: { categories: Array<{ name: string; description: string; paths: string[]; totalBytes: number; optional: boolean }>; totalPaths: number; totalSizeBytes: number; }; result?: { deletedPaths: string[]; failedPaths: string[]; totalSizeBytes: number; categorySummary: Record<string, { count: number; bytes: number }>; }; }> > { const { confirm, preserve_library = false } = args; log.info(`🔧 [TOOL] cleanup_data called`); log.info(` Confirm: ${confirm}`); log.info(` Preserve Library: ${preserve_library}`); const cleanupManager = new CleanupManager(); try { // Always run in deep mode const mode = "deep"; if (!confirm) { // Preview mode - show what would be deleted log.info(` 📋 Generating cleanup preview (mode: ${mode})...`); const preview = await cleanupManager.getCleanupPaths(mode, preserve_library); const platformInfo = cleanupManager.getPlatformInfo(); log.info(` Found ${preview.totalPaths.length} items (${cleanupManager.formatBytes(preview.totalSizeBytes)})`); log.info(` Platform: ${platformInfo.platform}`); return { success: true, data: { status: "preview", mode, preview: { categories: preview.categories, totalPaths: preview.totalPaths.length, totalSizeBytes: preview.totalSizeBytes, }, }, }; } else { // Cleanup mode - actually delete files log.info(` 🗑️ Performing cleanup (mode: ${mode})...`); const result = await cleanupManager.performCleanup(mode, preserve_library); if (result.success) { log.success(`✅ [TOOL] cleanup_data completed - deleted ${result.deletedPaths.length} items`); } else { log.warning(`⚠️ [TOOL] cleanup_data completed with ${result.failedPaths.length} errors`); } return { success: result.success, data: { status: result.success ? "completed" : "partial", mode, result: { deletedPaths: result.deletedPaths, failedPaths: result.failedPaths, totalSizeBytes: result.totalSizeBytes, categorySummary: result.categorySummary, }, }, }; } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); log.error(`❌ [TOOL] cleanup_data failed: ${errorMessage}`); return { success: false, error: errorMessage, }; } }
• src/tools/definitions/system.ts:112-153 (schema)

  Tool definition including name, detailed description, and inputSchema specifying 'confirm' (required boolean) and 'preserve_library' (optional boolean with default false).
  { name: "cleanup_data", description: "ULTRATHINK Deep Cleanup - Scans entire system for ALL NotebookLM MCP data files across 8 categories. Always runs in deep mode, shows categorized preview before deletion.\n\n" + "⚠️ CRITICAL: Close ALL Chrome/Chromium instances BEFORE running this tool! Open browsers can prevent cleanup and cause issues.\n\n" + "Categories scanned:\n" + "1. Legacy Installation (notebooklm-mcp-nodejs) - Old paths with -nodejs suffix\n" + "2. Current Installation (notebooklm-mcp) - Active data, browser profiles, library\n" + "3. NPM/NPX Cache - Cached installations from npx\n" + "4. Claude CLI MCP Logs - MCP server logs from Claude CLI\n" + "5. Temporary Backups - Backup directories in system temp\n" + "6. Claude Projects Cache - Project-specific cache (optional)\n" + "7. Editor Logs (Cursor/VSCode) - MCP logs from code editors (optional)\n" + "8. Trash Files - Deleted notebooklm files in system trash (optional)\n\n" + "Works cross-platform (Linux, Windows, macOS). Safe by design: shows detailed preview before deletion, requires explicit confirmation.\n\n" + "LIBRARY PRESERVATION: Set preserve_library=true to keep your notebook library.json file while cleaning everything else.\n\n" + "RECOMMENDED WORKFLOW for fresh start:\n" + "1. Ask user to close ALL Chrome/Chromium instances\n" + "2. Run cleanup_data(confirm=false, preserve_library=true) to preview\n" + "3. Run cleanup_data(confirm=true, preserve_library=true) to execute\n" + "4. Run setup_auth or re_auth for fresh browser session\n\n" + "Use cases: Clean reinstall, troubleshooting auth issues, removing all traces before uninstall, cleaning old browser sessions and installation data.", inputSchema: { type: "object", properties: { confirm: { type: "boolean", description: "Confirmation flag. Tool shows preview first, then user confirms deletion. " + "Set to true only after user has reviewed the preview and explicitly confirmed.", }, preserve_library: { type: "boolean", description: "Preserve library.json file during cleanup. Default: false. " + "Set to true to keep your notebook library while deleting everything else (browser data, caches, logs).", default: false, }, }, required: ["confirm"], }, },
• src/tools/definitions.ts:20-33 (registration)

  The buildToolDefinitions function aggregates all tool definitions, including systemTools (which contains cleanup_data), making it available to the MCP server via list_tools.
  export function buildToolDefinitions(library: NotebookLibrary): Tool[] { // Update the description for ask_question based on the library state const dynamicAskQuestionTool = { ...askQuestionTool, description: buildAskQuestionDescription(library), }; return [ dynamicAskQuestionTool, ...notebookManagementTools, ...sessionManagementTools, ...systemTools, ]; }
• src/index.ts:266-270 (registration)

  Dispatch case in the main MCP call_tool handler that routes 'cleanup_data' calls to the specific handleCleanupData method.
  case "cleanup_data": result = await this.toolHandlers.handleCleanupData( args as { confirm: boolean } ); break;