Webpage Screenshot MCP Server

Instructions

Implementation Reference

• src/index.ts:514-650 (handler)

  The handler function that implements the core logic for capturing screenshots of web pages using Puppeteer. Supports authentication via saved cookies, full-page screenshots, custom dimensions, formats, delays, browser visibility, and default system browser usage.

  async ({ url, fullPage, width, height, format, quality, waitFor, delay, useSavedAuth, reuseAuthPage, useDefaultBrowser, visibleBrowser }) => {
      let page: Page | null = null;
      let shouldClosePage = true;
      
      try {
          // Initialize browser with appropriate options
          const isHeadless = !visibleBrowser;
          const browserInstance = await initBrowser(isHeadless, useDefaultBrowser && visibleBrowser);
          
          // Check if we should reuse the authenticated page
          if (reuseAuthPage && persistentPage && !persistentPage.isClosed()) {
              page = persistentPage;
              shouldClosePage = false;
              
              // Navigate to the new URL if different
              const currentUrl = page.url();
              if (currentUrl !== url) {
                  await page.goto(url, {
                      waitUntil: waitFor as any,
                      timeout: 30000
                  });
              }
          } else {
              // Create a new page
              page = await browserInstance.newPage();
              
              // Load saved cookies if requested
              if (useSavedAuth) {
                  const cookies = await loadCookies(url);
                  if (cookies.length > 0) {
                      await page.setCookie(...cookies);
                  }
              }
              
              // Set viewport
              await page.setViewport({ width, height });
              
              // Set user agent to avoid bot detection
              await page.setUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36');
              
              // Additional anti-detection measures for Google
              await page.evaluateOnNewDocument(() => {
                  // Remove webdriver property
                  delete (window.navigator as any).webdriver;
                  
                  // Override the plugins property to add fake plugins
                  Object.defineProperty(window.navigator, 'plugins', {
                      get: () => [1, 2, 3, 4, 5]
                  });
                  
                  // Override the languages property
                  Object.defineProperty(window.navigator, 'languages', {
                      get: () => ['en-US', 'en']
                  });
                  
                  // Override permissions
                  Object.defineProperty(window.navigator, 'permissions', {
                      get: () => ({
                          query: () => Promise.resolve({ state: 'granted' })
                      })
                  });
              });
              
              // Navigate to the URL
              await page.goto(url, {
                  waitUntil: waitFor as any,
                  timeout: 30000
              });
          }
          
          // Optional delay
          if (delay > 0) {
              await new Promise(resolve => setTimeout(resolve, delay));
          }
          
          // Prepare screenshot options
          const screenshotOptions: any = {
              encoding: 'base64',
              fullPage,
              type: format
          };
          
          // Add quality option for jpeg and webp
          if ((format === 'jpeg' || format === 'webp') && quality !== undefined) {
              screenshotOptions.quality = quality;
          }
          
          // Take screenshot
          const screenshot = await page.screenshot(screenshotOptions) as string;
          
          // Get page title and final URL for context
          const pageTitle = await page.title();
          const finalUrl = page.url();
          
          // If using a new page, save any new cookies
          if (!reuseAuthPage && useSavedAuth) {
              const currentCookies = await page.cookies();
              if (currentCookies.length > 0) {
                  await saveCookies(url, currentCookies);
              }
          }
          
          // Determine browser type for response
          const browserType = useDefaultBrowser && visibleBrowser ? 'default browser' : 'Puppeteer browser';
          const browserMode = visibleBrowser ? 'visible' : 'headless';
          
          return {
              content: [
                  {
                      type: "text",
                      text: `Screenshot captured successfully!\n\nBrowser: ${browserType} (${browserMode})\nPage Title: ${pageTitle}\nFinal URL: ${finalUrl}\nFormat: ${format}\nDimensions: ${width}x${height}\nFull Page: ${fullPage}\nUsed saved auth: ${useSavedAuth}\nReused auth page: ${reuseAuthPage}`
                  },
                  {
                      type: "image",
                      data: screenshot,
                      mimeType: `image/${format}`
                  }
              ],
          };
      } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          return {
              isError: true,
              content: [
                  {
                      type: "text",
                      text: `Error capturing screenshot: ${errorMessage}`,
                  },
              ],
          };
      } finally {
          // Only close the page if it's not the persistent one or if we should close it
          if (page && shouldClosePage && page !== persistentPage) {
              await page.close().catch(() => {});
          }
      }
  }

• src/index.ts:500-513 (schema)

  Zod schema defining the input parameters for the screenshot-page tool, including URL, screenshot options, authentication flags, and browser configuration.

  {
      url: z.string().url().describe("The URL of the webpage to screenshot"),
      fullPage: z.boolean().optional().default(true).describe("Whether to capture the full page or just the viewport"),
      width: z.number().optional().default(1920).describe("Viewport width in pixels"),
      height: z.number().optional().default(1080).describe("Viewport height in pixels"),
      format: z.enum(['png', 'jpeg', 'webp']).optional().default('png').describe("Image format for the screenshot"),
      quality: z.number().min(0).max(100).optional().describe("Quality of the image (0-100), only applicable for jpeg and webp"),
      waitFor: z.enum(['load', 'domcontentloaded', 'networkidle0', 'networkidle2']).optional().default('networkidle2').describe("When to consider the page loaded"),
      delay: z.number().optional().default(0).describe("Additional delay in milliseconds to wait after page load"),
      useSavedAuth: z.boolean().optional().default(true).describe("Whether to use saved cookies from previous login"),
      reuseAuthPage: z.boolean().optional().default(false).describe("Whether to use the existing authenticated page instead of creating a new one"),
      useDefaultBrowser: z.boolean().optional().default(false).describe("Whether to use the system's default browser instead of Puppeteer's bundled Chromium"),
      visibleBrowser: z.boolean().optional().default(false).describe("Whether to show the browser window (non-headless mode)")
  },

• src/index.ts:496-651 (registration)

  Registration of the screenshot-page tool on the MCP server, including name, description, input schema, and handler function.

  // Updated screenshot-page tool with authentication support
  server.tool(
      "screenshot-page",
      "Captures a screenshot of a given URL and returns it as base64 encoded image. Can use saved cookies from login-and-wait.",
      {
          url: z.string().url().describe("The URL of the webpage to screenshot"),
          fullPage: z.boolean().optional().default(true).describe("Whether to capture the full page or just the viewport"),
          width: z.number().optional().default(1920).describe("Viewport width in pixels"),
          height: z.number().optional().default(1080).describe("Viewport height in pixels"),
          format: z.enum(['png', 'jpeg', 'webp']).optional().default('png').describe("Image format for the screenshot"),
          quality: z.number().min(0).max(100).optional().describe("Quality of the image (0-100), only applicable for jpeg and webp"),
          waitFor: z.enum(['load', 'domcontentloaded', 'networkidle0', 'networkidle2']).optional().default('networkidle2').describe("When to consider the page loaded"),
          delay: z.number().optional().default(0).describe("Additional delay in milliseconds to wait after page load"),
          useSavedAuth: z.boolean().optional().default(true).describe("Whether to use saved cookies from previous login"),
          reuseAuthPage: z.boolean().optional().default(false).describe("Whether to use the existing authenticated page instead of creating a new one"),
          useDefaultBrowser: z.boolean().optional().default(false).describe("Whether to use the system's default browser instead of Puppeteer's bundled Chromium"),
          visibleBrowser: z.boolean().optional().default(false).describe("Whether to show the browser window (non-headless mode)")
      },
      async ({ url, fullPage, width, height, format, quality, waitFor, delay, useSavedAuth, reuseAuthPage, useDefaultBrowser, visibleBrowser }) => {
          let page: Page | null = null;
          let shouldClosePage = true;
          
          try {
              // Initialize browser with appropriate options
              const isHeadless = !visibleBrowser;
              const browserInstance = await initBrowser(isHeadless, useDefaultBrowser && visibleBrowser);
              
              // Check if we should reuse the authenticated page
              if (reuseAuthPage && persistentPage && !persistentPage.isClosed()) {
                  page = persistentPage;
                  shouldClosePage = false;
                  
                  // Navigate to the new URL if different
                  const currentUrl = page.url();
                  if (currentUrl !== url) {
                      await page.goto(url, {
                          waitUntil: waitFor as any,
                          timeout: 30000
                      });
                  }
              } else {
                  // Create a new page
                  page = await browserInstance.newPage();
                  
                  // Load saved cookies if requested
                  if (useSavedAuth) {
                      const cookies = await loadCookies(url);
                      if (cookies.length > 0) {
                          await page.setCookie(...cookies);
                      }
                  }
                  
                  // Set viewport
                  await page.setViewport({ width, height });
                  
                  // Set user agent to avoid bot detection
                  await page.setUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36');
                  
                  // Additional anti-detection measures for Google
                  await page.evaluateOnNewDocument(() => {
                      // Remove webdriver property
                      delete (window.navigator as any).webdriver;
                      
                      // Override the plugins property to add fake plugins
                      Object.defineProperty(window.navigator, 'plugins', {
                          get: () => [1, 2, 3, 4, 5]
                      });
                      
                      // Override the languages property
                      Object.defineProperty(window.navigator, 'languages', {
                          get: () => ['en-US', 'en']
                      });
                      
                      // Override permissions
                      Object.defineProperty(window.navigator, 'permissions', {
                          get: () => ({
                              query: () => Promise.resolve({ state: 'granted' })
                          })
                      });
                  });
                  
                  // Navigate to the URL
                  await page.goto(url, {
                      waitUntil: waitFor as any,
                      timeout: 30000
                  });
              }
              
              // Optional delay
              if (delay > 0) {
                  await new Promise(resolve => setTimeout(resolve, delay));
              }
              
              // Prepare screenshot options
              const screenshotOptions: any = {
                  encoding: 'base64',
                  fullPage,
                  type: format
              };
              
              // Add quality option for jpeg and webp
              if ((format === 'jpeg' || format === 'webp') && quality !== undefined) {
                  screenshotOptions.quality = quality;
              }
              
              // Take screenshot
              const screenshot = await page.screenshot(screenshotOptions) as string;
              
              // Get page title and final URL for context
              const pageTitle = await page.title();
              const finalUrl = page.url();
              
              // If using a new page, save any new cookies
              if (!reuseAuthPage && useSavedAuth) {
                  const currentCookies = await page.cookies();
                  if (currentCookies.length > 0) {
                      await saveCookies(url, currentCookies);
                  }
              }
              
              // Determine browser type for response
              const browserType = useDefaultBrowser && visibleBrowser ? 'default browser' : 'Puppeteer browser';
              const browserMode = visibleBrowser ? 'visible' : 'headless';
              
              return {
                  content: [
                      {
                          type: "text",
                          text: `Screenshot captured successfully!\n\nBrowser: ${browserType} (${browserMode})\nPage Title: ${pageTitle}\nFinal URL: ${finalUrl}\nFormat: ${format}\nDimensions: ${width}x${height}\nFull Page: ${fullPage}\nUsed saved auth: ${useSavedAuth}\nReused auth page: ${reuseAuthPage}`
                      },
                      {
                          type: "image",
                          data: screenshot,
                          mimeType: `image/${format}`
                      }
                  ],
              };
          } catch (error) {
              const errorMessage = error instanceof Error ? error.message : String(error);
              return {
                  isError: true,
                  content: [
                      {
                          type: "text",
                          text: `Error capturing screenshot: ${errorMessage}`,
                      },
                  ],
              };
          } finally {
              // Only close the page if it's not the persistent one or if we should close it
              if (page && shouldClosePage && page !== persistentPage) {
                  await page.close().catch(() => {});
              }
          }
      }
  );

• src/index.ts:273-282 (helper)

  Helper function to load authentication cookies for a given URL/domain from persistent storage, used by screenshot-page for auth support.

  async function loadCookies(url: string): Promise<Cookie[]> {
      try {
          const domain = getDomainFromUrl(url);
          const cookiesPath = path.join(cookiesDir, `${domain}.json`);
          const cookiesData = await fsPromises.readFile(cookiesPath, 'utf-8');
          return JSON.parse(cookiesData);
      } catch {
          return [];
      }
  }

• src/index.ts:265-270 (helper)

  Helper function to save cookies for a domain after page load, enabling persistent authentication across tool calls.

  async function saveCookies(url: string, cookies: Cookie[]) {
      await ensureCookiesDir();
      const domain = getDomainFromUrl(url);
      const cookiesPath = path.join(cookiesDir, `${domain}.json`);
      await fsPromises.writeFile(cookiesPath, JSON.stringify(cookies, null, 2));
  }