screenshot
Capture screenshots of web pages or specific elements for documentation, testing, or content extraction. Configure viewport dimensions, image format, and quality settings.
Instructions
Capture a screenshot of the page or a specific element
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fullPage | No | Capture full scrollable page | |
| selector | No | Element to screenshot (screenshots viewport if not specified) | |
| format | No | png | |
| quality | No | Image quality (jpeg/webp only) | |
| width | No | Viewport width in pixels (default 1024) | |
| height | No | Viewport height in pixels (default 768) | |
| scale | No | Device scale factor (default 1, use 2 for retina) | |
| tabId | No | Tab ID to operate on (uses active tab if not specified) |
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';