Puppeteer MCP Server

Instructions

Implementation Reference

• src/tools/media.ts:22-85 (handler)

  The core handler function that executes the screenshot tool. It gets the page, sets viewport, captures screenshot of element or page, converts to base64, and returns as image content block.

  async ({ fullPage, selector, format, quality, width, height, scale, tabId }) => {
    const pageResult = await getPageForOperation(tabId);
    if (!pageResult.success) {
      return handleResult(pageResult);
    }
  
    const page = pageResult.data;
    const imageFormat = (format ?? 'png') as ScreenshotFormat;
  
    // Set viewport with sensible defaults for reasonable image sizes
    const viewportWidth = width ?? 1024;
    const viewportHeight = height ?? 768;
    const deviceScaleFactor = scale ?? 1;
  
    try {
      // Set viewport before screenshot to control resolution
      await page.setViewport({
        width: viewportWidth,
        height: viewportHeight,
        deviceScaleFactor,
      });
  
      let screenshotData: Uint8Array;
  
      if (selector) {
        // Screenshot specific element
        const element = await page.$(selector);
  
        if (!element) {
          return handleResult(err(selectorNotFound(selector)));
        }
  
        screenshotData = await element.screenshot({
          type: imageFormat,
          quality: imageFormat === 'png' ? undefined : (quality ?? 100),
        });
      } else {
        // Screenshot page/viewport
        screenshotData = await page.screenshot({
          fullPage: fullPage ?? false,
          type: imageFormat,
          quality: imageFormat === 'png' ? undefined : (quality ?? 100),
        });
      }
  
      const base64Data = Buffer.from(screenshotData).toString('base64');
      const mimeType = imageFormat === 'png' ? 'image/png'
        : imageFormat === 'jpeg' ? 'image/jpeg'
        : 'image/webp';
  
      // Return as image content block for efficient processing by Claude
      return {
        content: [
          {
            type: 'image' as const,
            data: base64Data,
            mimeType,
          },
        ],
      };
    } catch (error) {
      return handleResult(err(normalizeError(error)));
    }
  }

• src/schemas.ts:147-156 (schema)

  Zod schema for validating input parameters to the screenshot tool, including options for fullPage, selector, format, quality, dimensions, and tabId.

  export const screenshotSchema = z.object({
    fullPage: z.boolean().optional().default(false).describe('Capture full scrollable page'),
    selector: z.string().optional().describe('Element to screenshot (screenshots viewport if not specified)'),
    format: z.enum(['png', 'jpeg', 'webp']).optional().default('png'),
    quality: z.number().int().min(0).max(100).optional().describe('Image quality (jpeg/webp only)'),
    width: z.number().int().min(200).max(4000).optional().describe('Viewport width in pixels (default 1024)'),
    height: z.number().int().min(200).max(4000).optional().describe('Viewport height in pixels (default 768)'),
    scale: z.number().min(0.5).max(3).optional().describe('Device scale factor (default 1, use 2 for retina)'),
    tabId: tabIdSchema,
  });

• src/tools/media.ts:18-86 (registration)

  Registers the 'screenshot' tool on the MCP server using server.tool, providing name, description, input schema, and the handler function.

  server.tool(
    'screenshot',
    'Capture a screenshot of the page or a specific element',
    screenshotSchema.shape,
    async ({ fullPage, selector, format, quality, width, height, scale, tabId }) => {
      const pageResult = await getPageForOperation(tabId);
      if (!pageResult.success) {
        return handleResult(pageResult);
      }
  
      const page = pageResult.data;
      const imageFormat = (format ?? 'png') as ScreenshotFormat;
  
      // Set viewport with sensible defaults for reasonable image sizes
      const viewportWidth = width ?? 1024;
      const viewportHeight = height ?? 768;
      const deviceScaleFactor = scale ?? 1;
  
      try {
        // Set viewport before screenshot to control resolution
        await page.setViewport({
          width: viewportWidth,
          height: viewportHeight,
          deviceScaleFactor,
        });
  
        let screenshotData: Uint8Array;
  
        if (selector) {
          // Screenshot specific element
          const element = await page.$(selector);
  
          if (!element) {
            return handleResult(err(selectorNotFound(selector)));
          }
  
          screenshotData = await element.screenshot({
            type: imageFormat,
            quality: imageFormat === 'png' ? undefined : (quality ?? 100),
          });
        } else {
          // Screenshot page/viewport
          screenshotData = await page.screenshot({
            fullPage: fullPage ?? false,
            type: imageFormat,
            quality: imageFormat === 'png' ? undefined : (quality ?? 100),
          });
        }
  
        const base64Data = Buffer.from(screenshotData).toString('base64');
        const mimeType = imageFormat === 'png' ? 'image/png'
          : imageFormat === 'jpeg' ? 'image/jpeg'
          : 'image/webp';
  
        // Return as image content block for efficient processing by Claude
        return {
          content: [
            {
              type: 'image' as const,
              data: base64Data,
              mimeType,
            },
          ],
        };
      } catch (error) {
        return handleResult(err(normalizeError(error)));
      }
    }
  );

• src/server.ts:27-27 (registration)

  Invokes registerMediaTools during server setup, which in turn registers the screenshot tool among media tools.

  registerMediaTools(server);

• src/types.ts:162-162 (schema)

  Type definition for supported screenshot formats used in the handler.

  export type ScreenshotFormat = 'png' | 'jpeg' | 'webp';