screenshot

Capture web page screenshots at multiple viewport breakpoints using Puppeteer, with options for page interactions, session persistence, and image optimization.

Instructions

Capture screenshots of web pages at multiple viewport breakpoints using Puppeteer

Input Schema

TableJSON Schema

Name	Required	Description	Default
`url`	Yes	URL to capture screenshots from
`breakpoints`	No	Viewport breakpoints (optional, defaults to mobile: 375px, tablet: 768px, desktop: 1280px)
`headless`	No	Run browser in headless mode
`waitFor`	No	Wait condition before capturing screenshot	networkidle0
`timeout`	No	Navigation timeout in milliseconds
`maxWidth`	No	Maximum width for image optimization (images wider than this will be clipped)
`imageFormat`	No	Image format (JPEG recommended for smaller file sizes)	jpeg
`quality`	No	JPEG quality (1-100, only applies when imageFormat is 'jpeg')
`actions`	No	Array of page interactions to perform before taking screenshots
`sessionId`	No	Session identifier for persistent browser state (maintains cookies, login data, localStorage, etc.)
`userDataDir`	No	Custom user data directory path for browser session storage
`cookies`	No	Cookies to inject into the browser session before navigation

Implementation Reference

src/tools/screenshotTool.ts:322-504 (handler)

Core handler function that launches Puppeteer browser, navigates to URL, performs optional actions, captures screenshots at specified breakpoints, collects errors, and returns base64 images with metadata.

export async function screenshotTool(args: any): Promise<ScreenshotResult> {
  const {
    url,
    breakpoints = DEFAULT_BREAKPOINTS,
    headless = true,
    waitFor = "networkidle0",
    timeout = 30000,
    maxWidth = 1280, // Default max width for optimization
    imageFormat = "jpeg", // Default to JPEG for smaller file size
    quality = 80, // Default JPEG quality
    actions = [], // Default empty actions array
    sessionId,
    userDataDir,
    cookies,
  }: ScreenshotArgs = args;

  // Determine user data directory for session info
  let finalUserDataDir: string | undefined;
  if (sessionId || userDataDir) {
    if (userDataDir) {
      finalUserDataDir = userDataDir;
    } else if (sessionId) {
      finalUserDataDir = path.join(os.tmpdir(), 'puppeteer-mcp-sessions', sessionId);
    }
  }

  if (!url) {
    return {
      success: false,
      screenshots: [],
      pageErrors: [],
      errorSummary: {
        totalErrors: 0,
        totalWarnings: 0,
        totalLogs: 0,
        hasJavaScriptErrors: false,
        hasNetworkErrors: false,
        hasConsoleLogs: false,
      },
      error: "URL is required"
    };
  }

  try {
    const browser = await getBrowser(headless, sessionId, userDataDir);
    const page = await browser.newPage();
    
    // Start collecting errors
    const pageErrors = await collectPageErrors(page);
    
    const results = [];
    
    for (const breakpoint of breakpoints) {
      const startTime = Date.now();
      
      // Determine if we need to optimize this breakpoint
      const shouldOptimize = breakpoint.width > maxWidth;
      const screenshotWidth = shouldOptimize ? maxWidth : breakpoint.width;
      
      // Set viewport
      await page.setViewport({ 
        width: breakpoint.width, 
        height: 800 // Initial height, will capture full page
      });
      
      // Set cookies before navigation if provided
      if (cookies && cookies.length > 0) {
        await setCookies(page, cookies, url);
      }
      
      // Navigate to URL
      await page.goto(url, { 
        waitUntil: waitFor as any,
        timeout 
      });
      
      // Execute page actions if provided
      if (actions.length > 0) {
        await executePageActions(page, actions);
      }
      
      // Get actual content dimensions
      const actualContentSize = await getFullPageDimensions(page);
      
      // Configure screenshot options
      const screenshotOptions: any = {
        fullPage: true,
        encoding: 'base64'
      };
      
      // Set format and quality
      if (imageFormat === "jpeg") {
        screenshotOptions.type = 'jpeg';
        screenshotOptions.quality = quality;
      } else {
        screenshotOptions.type = 'png';
      }
      
      // If we need to optimize, clip the screenshot width
      if (shouldOptimize) {
        screenshotOptions.clip = {
          x: 0,
          y: 0,
          width: maxWidth,
          height: actualContentSize.height
        };
      }
      
      // Take screenshot
      const screenshot = await page.screenshot(screenshotOptions);
      
      const loadTime = Date.now() - startTime;
      
      // Determine the data URL prefix based on format
      const mimeType = imageFormat === "jpeg" ? "image/jpeg" : "image/png";
      const dataPrefix = `data:${mimeType};base64,`;
      
      results.push({
        width: shouldOptimize ? maxWidth : breakpoint.width,
        height: actualContentSize.height,
        screenshot: `${dataPrefix}${screenshot}`,
        format: imageFormat,
        metadata: {
          viewport: { width: breakpoint.width, height: 800 },
          actualContentSize,
          loadTime,
          timestamp: new Date().toISOString(),
          optimized: shouldOptimize,
          originalSize: shouldOptimize ? { width: breakpoint.width, height: actualContentSize.height } : undefined,
        },
      });
    }
    
    await page.close();
    
    // Create error summary
    const errors = pageErrors.filter(e => e.level === 'error');
    const warnings = pageErrors.filter(e => e.level === 'warning');
    const logs = pageErrors.filter(e => e.level === 'info');
    const errorSummary = {
      totalErrors: errors.length,
      totalWarnings: warnings.length,
      totalLogs: logs.length,
      hasJavaScriptErrors: pageErrors.some(e => e.type === 'javascript' && e.level === 'error'),
      hasNetworkErrors: pageErrors.some(e => e.type === 'network' && e.level === 'error'),
      hasConsoleLogs: pageErrors.some(e => e.type === 'console' && e.level === 'info'),
    };
    
    const result: ScreenshotResult = {
      success: true,
      screenshots: results,
      pageErrors,
      errorSummary,
    };

    // Add session info if session was used
    if (sessionId) {
      result.sessionInfo = {
        sessionId,
        userDataDir: finalUserDataDir || path.join(os.tmpdir(), 'puppeteer-mcp-sessions', sessionId),
        persistent: true,
      };
    }
    
    return result;
    
  } catch (error) {
    return {
      success: false,
      screenshots: [],
      pageErrors: [],
      errorSummary: {
        totalErrors: 0,
        totalWarnings: 0,
        totalLogs: 0,
        hasJavaScriptErrors: false,
        hasNetworkErrors: false,
        hasConsoleLogs: false,
      },
      error: error instanceof Error ? error.message : String(error)
    };
  }
}

src/index.ts:25-193 (registration)

Registers the 'screenshot' tool by defining it in the ListTools response, including name, description, and input schema.

// Register available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "screenshot",
        description: "Capture screenshots of web pages at multiple viewport breakpoints using Puppeteer",
        inputSchema: {
          type: "object",
          properties: {
            url: {
              type: "string",
              description: "URL to capture screenshots from"
            },
            breakpoints: {
              type: "array",
              items: {
                type: "object",
                properties: {
                  width: { 
                    type: "number",
                    description: "Viewport width in pixels"
                  }
                },
                required: ["width"]
              },
              description: "Viewport breakpoints (optional, defaults to mobile: 375px, tablet: 768px, desktop: 1280px)"
            },
            headless: {
              type: "boolean",
              description: "Run browser in headless mode",
              default: true
            },
            waitFor: {
              type: "string",
              enum: ["load", "domcontentloaded", "networkidle0", "networkidle2"],
              description: "Wait condition before capturing screenshot",
              default: "networkidle0"
            },
            timeout: {
              type: "number",
              description: "Navigation timeout in milliseconds",
              default: 30000
            },
            maxWidth: {
              type: "number",
              description: "Maximum width for image optimization (images wider than this will be clipped)",
              default: 1280
            },
            imageFormat: {
              type: "string",
              enum: ["png", "jpeg"],
              description: "Image format (JPEG recommended for smaller file sizes)",
              default: "jpeg"
            },
            quality: {
              type: "number",
              minimum: 1,
              maximum: 100,
              description: "JPEG quality (1-100, only applies when imageFormat is 'jpeg')",
              default: 80
            },
            actions: {
              type: "array",
              items: {
                type: "object",
                properties: {
                  type: {
                    type: "string",
                    enum: ["click", "type", "scroll", "wait", "hover", "select", "clear", "navigate", "waitForElement"],
                    description: "Type of action to perform"
                  },
                  selector: {
                    type: "string",
                    description: "CSS selector for element-based actions"
                  },
                  text: {
                    type: "string",
                    description: "Text to type (for type action)"
                  },
                  value: {
                    type: "string",
                    description: "Value to select (for select action)"
                  },
                  x: {
                    type: "number",
                    description: "X coordinate (for scroll action)"
                  },
                  y: {
                    type: "number",
                    description: "Y coordinate (for scroll action)"
                  },
                  duration: {
                    type: "number",
                    description: "Duration in milliseconds (for wait action)",
                    default: 1000
                  },
                  url: {
                    type: "string",
                    description: "URL to navigate to (for navigate action)"
                  },
                  timeout: {
                    type: "number",
                    description: "Timeout in milliseconds (for waitForElement action)",
                    default: 5000
                  }
                },
                required: ["type"]
              },
              description: "Array of page interactions to perform before taking screenshots"
            },
            sessionId: {
              type: "string",
              description: "Session identifier for persistent browser state (maintains cookies, login data, localStorage, etc.)"
            },
            userDataDir: {
              type: "string",
              description: "Custom user data directory path for browser session storage"
            },
            cookies: {
              type: "array",
              items: {
                type: "object",
                properties: {
                  name: {
                    type: "string",
                    description: "Cookie name"
                  },
                  value: {
                    type: "string", 
                    description: "Cookie value"
                  },
                  domain: {
                    type: "string",
                    description: "Cookie domain (optional, defaults to URL domain)"
                  },
                  path: {
                    type: "string",
                    description: "Cookie path (optional, defaults to '/')"
                  },
                  expires: {
                    type: "number",
                    description: "Cookie expiration timestamp (optional)"
                  },
                  httpOnly: {
                    type: "boolean",
                    description: "HttpOnly flag (optional)"
                  },
                  secure: {
                    type: "boolean", 
                    description: "Secure flag (optional)"
                  },
                  sameSite: {
                    type: "string",
                    enum: ["Strict", "Lax", "None"],
                    description: "SameSite policy (optional)"
                  }
                },
                required: ["name", "value"]
              },
              description: "Cookies to inject into the browser session before navigation"
            }
          },
          required: ["url"]
        }
      }
    ]
  };
});

src/index.ts:32-189 (schema)

Defines the input schema for the screenshot tool, specifying parameters like url, breakpoints, actions, cookies, etc.

inputSchema: {
  type: "object",
  properties: {
    url: {
      type: "string",
      description: "URL to capture screenshots from"
    },
    breakpoints: {
      type: "array",
      items: {
        type: "object",
        properties: {
          width: { 
            type: "number",
            description: "Viewport width in pixels"
          }
        },
        required: ["width"]
      },
      description: "Viewport breakpoints (optional, defaults to mobile: 375px, tablet: 768px, desktop: 1280px)"
    },
    headless: {
      type: "boolean",
      description: "Run browser in headless mode",
      default: true
    },
    waitFor: {
      type: "string",
      enum: ["load", "domcontentloaded", "networkidle0", "networkidle2"],
      description: "Wait condition before capturing screenshot",
      default: "networkidle0"
    },
    timeout: {
      type: "number",
      description: "Navigation timeout in milliseconds",
      default: 30000
    },
    maxWidth: {
      type: "number",
      description: "Maximum width for image optimization (images wider than this will be clipped)",
      default: 1280
    },
    imageFormat: {
      type: "string",
      enum: ["png", "jpeg"],
      description: "Image format (JPEG recommended for smaller file sizes)",
      default: "jpeg"
    },
    quality: {
      type: "number",
      minimum: 1,
      maximum: 100,
      description: "JPEG quality (1-100, only applies when imageFormat is 'jpeg')",
      default: 80
    },
    actions: {
      type: "array",
      items: {
        type: "object",
        properties: {
          type: {
            type: "string",
            enum: ["click", "type", "scroll", "wait", "hover", "select", "clear", "navigate", "waitForElement"],
            description: "Type of action to perform"
          },
          selector: {
            type: "string",
            description: "CSS selector for element-based actions"
          },
          text: {
            type: "string",
            description: "Text to type (for type action)"
          },
          value: {
            type: "string",
            description: "Value to select (for select action)"
          },
          x: {
            type: "number",
            description: "X coordinate (for scroll action)"
          },
          y: {
            type: "number",
            description: "Y coordinate (for scroll action)"
          },
          duration: {
            type: "number",
            description: "Duration in milliseconds (for wait action)",
            default: 1000
          },
          url: {
            type: "string",
            description: "URL to navigate to (for navigate action)"
          },
          timeout: {
            type: "number",
            description: "Timeout in milliseconds (for waitForElement action)",
            default: 5000
          }
        },
        required: ["type"]
      },
      description: "Array of page interactions to perform before taking screenshots"
    },
    sessionId: {
      type: "string",
      description: "Session identifier for persistent browser state (maintains cookies, login data, localStorage, etc.)"
    },
    userDataDir: {
      type: "string",
      description: "Custom user data directory path for browser session storage"
    },
    cookies: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: {
            type: "string",
            description: "Cookie name"
          },
          value: {
            type: "string", 
            description: "Cookie value"
          },
          domain: {
            type: "string",
            description: "Cookie domain (optional, defaults to URL domain)"
          },
          path: {
            type: "string",
            description: "Cookie path (optional, defaults to '/')"
          },
          expires: {
            type: "number",
            description: "Cookie expiration timestamp (optional)"
          },
          httpOnly: {
            type: "boolean",
            description: "HttpOnly flag (optional)"
          },
          secure: {
            type: "boolean", 
            description: "Secure flag (optional)"
          },
          sameSite: {
            type: "string",
            enum: ["Strict", "Lax", "None"],
            description: "SameSite policy (optional)"
          }
        },
        required: ["name", "value"]
      },
      description: "Cookies to inject into the browser session before navigation"
    }
  },
  required: ["url"]
}

src/index.ts:195-321 (handler)

MCP dispatch handler for tool calls; checks if name is 'screenshot', invokes screenshotTool, formats response with summaries and embedded images.

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  try {
    if (request.params.name === "screenshot") {
      const result = await screenshotTool(request.params.arguments);
      
      if (!result.success) {
        throw new McpError(
          ErrorCode.InternalError,
          result.error || "Screenshot capture failed"
        );
      }
      
      // Build content array with text description and images
      const content = [];
      
      // Add summary text with error information
      let summaryText = `Successfully captured ${result.screenshots.length} screenshot(s) for ${request.params.arguments?.url || 'the requested URL'}`;
      
      // Add actions summary if actions were provided
      if (request.params.arguments?.actions && Array.isArray(request.params.arguments.actions) && request.params.arguments.actions.length > 0) {
        const actionTypes = request.params.arguments.actions.map((action: any) => action.type);
        summaryText += `\n🎯 Executed ${actionTypes.length} page action(s): ${actionTypes.join(', ')}`;
      }
      
      // Add session info if session was used
      if (result.sessionInfo) {
        summaryText += `\n🔒 Session: ${result.sessionInfo.sessionId} (persistent login data maintained)`;
      }
      
      // Add error summary if there are any issues
      if (result.errorSummary.totalErrors > 0 || result.errorSummary.totalWarnings > 0 || result.errorSummary.totalLogs > 0) {
        summaryText += `\n\n📊 Page Activity Detected:`;
        if (result.errorSummary.totalErrors > 0) {
          summaryText += `\n• ${result.errorSummary.totalErrors} error(s)`;
        }
        if (result.errorSummary.totalWarnings > 0) {
          summaryText += `\n• ${result.errorSummary.totalWarnings} warning(s)`;
        }
        if (result.errorSummary.totalLogs > 0) {
          summaryText += `\n• ${result.errorSummary.totalLogs} console log(s)`;
        }
        if (result.errorSummary.hasJavaScriptErrors) {
          summaryText += `\n• JavaScript errors present`;
        }
        if (result.errorSummary.hasNetworkErrors) {
          summaryText += `\n• Network/loading errors present`;
        }
        if (result.errorSummary.hasConsoleLogs) {
          summaryText += `\n• Console logs available`;
        }
      } else {
        summaryText += `\n✅ No errors, warnings, or console activity detected`;
      }
      
      content.push({
        type: "text",
        text: summaryText
      });
      
      // Add detailed error information if present
      if (result.pageErrors.length > 0) {
        let errorDetails = "\n📋 Detailed Error Report:\n";
        
        // Group errors by type
        const errorsByType = result.pageErrors.reduce((acc, error) => {
          if (!acc[error.type]) acc[error.type] = [];
          acc[error.type].push(error);
          return acc;
        }, {} as Record<string, typeof result.pageErrors>);
        
        Object.entries(errorsByType).forEach(([type, errors]) => {
          errorDetails += `\n${type.toUpperCase()} ISSUES (${errors.length}):\n`;
          errors.forEach((error, index) => {
            const icon = error.level === 'error' ? '❌' : '⚠️';
            errorDetails += `${icon} ${error.message}`;
            if (error.source) errorDetails += `\n   Source: ${error.source}`;
            if (error.line && error.column) errorDetails += ` (line ${error.line}, col ${error.column})`;
            if (error.url && error.url !== error.source) errorDetails += `\n   URL: ${error.url}`;
            if (error.statusCode) errorDetails += ` [${error.statusCode}]`;
            errorDetails += `\n   Time: ${new Date(error.timestamp).toLocaleTimeString()}\n`;
          });
        });
        
        content.push({
          type: "text",
          text: errorDetails
        });
      }
      
      // Add each screenshot as an image
      for (const screenshot of result.screenshots) {
        // Extract base64 data - handle both PNG and JPEG formats
        const base64Data = screenshot.screenshot.replace(/^data:image\/(png|jpeg);base64,/, '');
        const mimeType = screenshot.format === "jpeg" ? "image/jpeg" : "image/png";
        
        // Add minimal description
        content.push({
          type: "text",
          text: `${screenshot.width}px viewport (${screenshot.format.toUpperCase()})`
        });
        
        content.push({
          type: "image",
          data: base64Data,
          mimeType: mimeType
        });
      }
      
      return { content };
    }
    
    throw new McpError(
      ErrorCode.MethodNotFound,
      `Unknown tool: ${request.params.name}`
    );
  } catch (error) {
    if (error instanceof McpError) {
      throw error;
    }
    
    throw new McpError(
      ErrorCode.InternalError,
      `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
    );
  }
});

src/tools/screenshotTool.ts:18-85 (helper)

TypeScript interfaces defining inputs (ScreenshotArgs), outputs (ScreenshotResult), actions (PageAction), and errors (PageError) for the screenshot tool.

export interface ScreenshotArgs {
  url: string;
  breakpoints?: { width: number }[];
  headless?: boolean;
  waitFor?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
  timeout?: number;
  maxWidth?: number; // Max width for optimization
  imageFormat?: "png" | "jpeg";
  quality?: number; // JPEG quality (0-100)
  actions?: PageAction[]; // Array of actions to perform before screenshot
  sessionId?: string; // Session identifier for persistent browser state
  userDataDir?: string; // Custom user data directory path
  cookies?: Array<{ // NEW: Cookies to inject into the session
    name: string;
    value: string;
    domain?: string;
    path?: string;
    expires?: number;
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: "Strict" | "Lax" | "None";
  }>;
}

export interface PageError {
  type: "javascript" | "console" | "network" | "security";
  level: "error" | "warning" | "info";
  message: string;
  source?: string;
  line?: number;
  column?: number;
  timestamp: string;
  url?: string;
  statusCode?: number;
}

export interface ScreenshotResult {
  success: boolean;
  screenshots: {
    width: number;
    height: number;
    screenshot: string;
    format: string;
    metadata: {
      viewport: { width: number; height: number };
      actualContentSize: { width: number; height: number };
      loadTime: number;
      timestamp: string;
      optimized: boolean;
      originalSize?: { width: number; height: number };
    };
  }[];
  pageErrors: PageError[];
  errorSummary: {
    totalErrors: number;
    totalWarnings: number;
    totalLogs: number;
    hasJavaScriptErrors: boolean;
    hasNetworkErrors: boolean;
    hasConsoleLogs: boolean;
  };
  error?: string;
  sessionInfo?: {
    sessionId: string;
    userDataDir: string;
    persistent: boolean;
  };
}

PuppeteerMCP Server

screenshot

Instructions

Input Schema

Implementation Reference

Other Tools

Latest Blog Posts

MCP directory API