PuppeteerMCP Server

Instructions

Implementation Reference

• build/tools/screenshotTool.js:222-373 (handler)

  The core handler function `screenshotTool` that implements the screenshot capture logic using Puppeteer. It handles browser launching, page navigation, optional actions, error collection, and screenshot taking at multiple breakpoints.
  export async function screenshotTool(args) { 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, } = args; // Determine user data directory for session info let finalUserDataDir; 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, 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 = { 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 = { 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) }; } }
• build/index.js:15-182 (registration)

  Tool registration in the MCP server's ListToolsRequestSchema handler, defining the 'screenshot' tool name, description, and complete input JSON schema.
  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"] } } ] }; });
• build/index.js:184-290 (handler)

  The MCP CallTool request handler that dispatches to the screenshotTool implementation when the tool name is 'screenshot', processes the result into MCP content format with images and summaries.
  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) => 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; }, {}); 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-40 (schema)

  TypeScript interface defining the input schema for the screenshot tool parameters.
  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"; }>; }
• build/tools/screenshotTool.js:55-118 (helper)

  Helper function to collect page errors, warnings, and logs during screenshot capture for diagnostic reporting.
  async function collectPageErrors(page) { const errors = []; // Collect JavaScript errors page.on('pageerror', (error) => { errors.push({ type: "javascript", level: "error", message: error.message, source: error.stack?.split('\n')[0] || '', timestamp: new Date().toISOString() }); }); // Collect console messages (errors, warnings, logs, info, debug) page.on('console', (msg) => { const msgType = msg.type(); // Determine level based on console type let level; if (msgType === 'error' || msgType === 'assert') { level = "error"; } else if (msgType === 'warning') { level = "warning"; } else { level = "info"; // For log, info, debug, etc. } errors.push({ type: "console", level: level, message: msg.text(), source: msg.location()?.url, line: msg.location()?.lineNumber, column: msg.location()?.columnNumber, timestamp: new Date().toISOString() }); }); // Collect network failures page.on('response', (response) => { if (!response.ok()) { errors.push({ type: "network", level: response.status() >= 500 ? "error" : "warning", message: `Failed to load resource: ${response.status()} ${response.statusText()}`, url: response.url(), statusCode: response.status(), timestamp: new Date().toISOString() }); } }); // Collect security/CORS errors page.on('requestfailed', (request) => { const failure = request.failure(); if (failure) { errors.push({ type: failure.errorText.includes('CORS') ? "security" : "network", level: "error", message: `Request failed: ${failure.errorText}`, url: request.url(), timestamp: new Date().toISOString() }); } }); return errors; }