NotebookLM MCP Server

Instructions

Implementation Reference

• src/tools/handlers.ts:396-475 (handler)

  Main handler for setup_auth tool. Handles arguments, progress reporting, configuration overrides, calls AuthManager.performSetup, and returns structured result.
  async handleSetupAuth( args: { show_browser?: boolean; browser_options?: BrowserOptions; }, sendProgress?: ProgressCallback ): Promise< ToolResult<{ status: string; message: string; authenticated: boolean; duration_seconds?: number; }> > { const { show_browser, browser_options } = args; // CRITICAL: Send immediate progress to reset timeout from the very start await sendProgress?.("Initializing authentication setup...", 0, 10); log.info(`🔧 [TOOL] setup_auth called`); if (show_browser !== undefined) { log.info(` Show browser: ${show_browser}`); } const startTime = Date.now(); // Apply browser options temporarily const originalConfig = { ...CONFIG }; const effectiveConfig = applyBrowserOptions(browser_options, show_browser); Object.assign(CONFIG, effectiveConfig); try { // Progress: Starting await sendProgress?.("Preparing authentication browser...", 1, 10); log.info(` 🌐 Opening browser for interactive login...`); // Progress: Opening browser await sendProgress?.("Opening browser window...", 2, 10); // Perform setup with progress updates (uses CONFIG internally) const success = await this.authManager.performSetup(sendProgress); const durationSeconds = (Date.now() - startTime) / 1000; if (success) { // Progress: Complete await sendProgress?.("Authentication saved successfully!", 10, 10); log.success(`✅ [TOOL] setup_auth completed (${durationSeconds.toFixed(1)}s)`); return { success: true, data: { status: "authenticated", message: "Successfully authenticated and saved browser state", authenticated: true, duration_seconds: durationSeconds, }, }; } else { log.error(`❌ [TOOL] setup_auth failed (${durationSeconds.toFixed(1)}s)`); return { success: false, error: "Authentication failed or was cancelled", }; } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); const durationSeconds = (Date.now() - startTime) / 1000; log.error(`❌ [TOOL] setup_auth failed: ${errorMessage} (${durationSeconds.toFixed(1)}s)`); return { success: false, error: errorMessage, }; } finally { // Restore original CONFIG Object.assign(CONFIG, originalConfig); } }
• src/tools/definitions/system.ts:17-59 (schema)

  Tool definition and input schema for setup_auth, including detailed description and optional browser configuration parameters.
  name: "setup_auth", description: "Google authentication for NotebookLM access - opens a browser window for manual login to your Google account. " + "Returns immediately after opening the browser. You have up to 10 minutes to complete the login. " + "Use 'get_health' tool afterwards to verify authentication was saved successfully. " + "Use this for first-time authentication or when auto-login credentials are not available. " + "For switching accounts or rate-limit workarounds, use 're_auth' tool instead.\n\n" + "TROUBLESHOOTING for persistent auth issues:\n" + "If setup_auth fails or you encounter browser/session issues:\n" + "1. Ask user to close ALL Chrome/Chromium instances\n" + "2. Run cleanup_data(confirm=true, preserve_library=true) to clean old data\n" + "3. Run setup_auth again for fresh start\n" + "This helps resolve conflicts from old browser sessions and installation data.", inputSchema: { type: "object", properties: { show_browser: { type: "boolean", description: "Show browser window (simple version). Default: true for setup. " + "For advanced control, use browser_options instead.", }, browser_options: { type: "object", description: "Optional browser settings. Control visibility, timeouts, and stealth behavior.", properties: { show: { type: "boolean", description: "Show browser window (default: true for setup)", }, headless: { type: "boolean", description: "Run browser in headless mode (default: false for setup)", }, timeout_ms: { type: "number", description: "Browser operation timeout in milliseconds (default: 30000)", }, }, }, }, },
• src/index.ts:252-257 (registration)

  Dispatches setup_auth tool calls to the appropriate handler method in the MCP server request handler.
  case "setup_auth": result = await this.toolHandlers.handleSetupAuth( args as { show_browser?: boolean }, sendProgress ); break;
• src/auth/auth-manager.ts:914-976 (helper)

  Key helper method performSetup in AuthManager, launched by the tool handler. Manages persistent browser context for interactive authentication, data clearing, login, and state persistence.
  async performSetup(sendProgress?: ProgressCallback, overrideHeadless?: boolean): Promise<boolean> { const { chromium } = await import("patchright"); // Determine headless mode: override or default to true (visible for setup) // overrideHeadless contains show_browser value (true = show, false = hide) const shouldShowBrowser = overrideHeadless !== undefined ? overrideHeadless : true; try { // CRITICAL: Clear ALL old auth data FIRST (for account switching) log.info("🔄 Preparing for new account authentication..."); await sendProgress?.("Clearing old authentication data...", 1, 10); await this.clearAllAuthData(); log.info("🚀 Launching persistent browser for interactive setup..."); log.info(` 📍 Profile: ${CONFIG.chromeProfileDir}`); await sendProgress?.("Launching persistent browser...", 2, 10); // ✅ CRITICAL FIX: Use launchPersistentContext (same as runtime!) // This ensures session cookies persist correctly const context = await chromium.launchPersistentContext( CONFIG.chromeProfileDir, { headless: !shouldShowBrowser, // Use override or default to visible for setup channel: "chrome" as const, viewport: CONFIG.viewport, locale: "en-US", timezoneId: "Europe/Berlin", args: [ "--disable-blink-features=AutomationControlled", "--disable-dev-shm-usage", "--no-first-run", "--no-default-browser-check", ], } ); // Get or create a page const pages = context.pages(); const page = pages.length > 0 ? pages[0] : await context.newPage(); // Perform login with progress updates const loginSuccess = await this.performLogin(page, sendProgress); if (loginSuccess) { // ✅ Save browser state to state.json (for validation & backup) // Chrome ALSO saves everything to the persistent profile automatically! await sendProgress?.("Saving authentication state...", 9, 10); await this.saveBrowserState(context, page); log.success("✅ Setup complete - authentication saved to:"); log.success(` 📄 State file: ${this.stateFilePath}`); log.success(` 📁 Chrome profile: ${CONFIG.chromeProfileDir}`); log.info("💡 Session cookies will now persist across restarts!"); } // Close persistent context await context.close(); return loginSuccess; } catch (error) { log.error(`❌ Setup failed: ${error}`); return false; } }