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;
    }
  }