PuppeteerMCP Server

Instructions

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