playwright_screenshot

Capture screenshots of web pages or specific elements. Configure width, height, and format, or save as PNG. Supports full-page captures and custom directories for file storage.

Instructions

Take a screenshot of the current page or a specific element

Input Schema

TableJSON Schema

Name	Required	Description
`downloadsDir`	No	Custom downloads directory path (default: user's Downloads folder)
`fullPage`	No	Store screenshot of the entire page (default: false)
`height`	No	Height in pixels (default: 600)
`name`	Yes	Name for the screenshot
`savePng`	No	Save screenshot as PNG file (default: false)
`selector`	No	CSS selector for element to screenshot
`storeBase64`	No	Store screenshot in base64 format (default: true)
`width`	No	Width in pixels (default: 800)

Implementation Reference

src/tools/browser/screenshot.ts:13-77 (handler)

The ScreenshotTool class provides the core implementation of the playwright_screenshot tool, including the execute method that takes screenshots of the page or elements using Playwright's page.screenshot.

export class ScreenshotTool extends BrowserToolBase {
  private screenshots = new Map<string, string>();

  /**
   * Execute the screenshot tool
   */
  async execute(args: any, context: ToolContext): Promise<ToolResponse> {
    return this.safeExecute(context, async (page) => {
      const screenshotOptions: any = {
        type: args.type || "png",
        fullPage: !!args.fullPage
      };

      if (args.selector) {
        const element = await page.$(args.selector);
        if (!element) {
          return {
            content: [{
              type: "text",
              text: `Element not found: ${args.selector}`,
            }],
            isError: true
          };
        }
        screenshotOptions.element = element;
      }

      // Generate output path
      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
      const filename = `${args.name || 'screenshot'}-${timestamp}.png`;
      const downloadsDir = args.downloadsDir || defaultDownloadsPath;

      if (!fs.existsSync(downloadsDir)) {
        fs.mkdirSync(downloadsDir, { recursive: true });
      }

      const outputPath = path.join(downloadsDir, filename);
      screenshotOptions.path = outputPath;

      const screenshot = await page.screenshot(screenshotOptions);
      const base64Screenshot = screenshot.toString('base64');

      const messages = [`Screenshot saved to: ${path.relative(process.cwd(), outputPath)}`];

      // Handle base64 storage
      if (args.storeBase64 !== false) {
        this.screenshots.set(args.name || 'screenshot', base64Screenshot);
        this.server.notification({
          method: "notifications/resources/list_changed",
        });

        messages.push(`Screenshot also stored in memory with name: '${args.name || 'screenshot'}'`);
      }

      return createSuccessResponse(messages);
    });
  }

  /**
   * Get all stored screenshots
   */
  getScreenshots(): Map<string, string> {
    return this.screenshots;
  }
}

src/tools.ts:95-112 (schema)

Tool schema definition including name, description, and inputSchema for validation.

{
  name: "playwright_screenshot",
  description: "Take a screenshot of the current page or a specific element",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string", description: "Name for the screenshot" },
      selector: { type: "string", description: "CSS selector for element to screenshot" },
      width: { type: "number", description: "Width in pixels (default: 800)" },
      height: { type: "number", description: "Height in pixels (default: 600)" },
      storeBase64: { type: "boolean", description: "Store screenshot in base64 format (default: true)" },
      fullPage: { type: "boolean", description: "Store screenshot of the entire page (default: false)" },
      savePng: { type: "boolean", description: "Save screenshot as PNG file (default: false)" },
      downloadsDir: { type: "string", description: "Custom downloads directory path (default: user's Downloads folder)" },
    },
    required: ["name"],
  },
},

src/toolHandler.ts:475-476 (registration)
Registration in the main tool handler switch statement, dispatching to the ScreenshotTool execute method.
```
case "playwright_screenshot":
  return await screenshotTool.execute(args, context);
```

src/tools.ts:96-112 (registration)

Tool is defined and registered in createToolDefinitions() function for MCP tool registry.

  name: "playwright_screenshot",
  description: "Take a screenshot of the current page or a specific element",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string", description: "Name for the screenshot" },
      selector: { type: "string", description: "CSS selector for element to screenshot" },
      width: { type: "number", description: "Width in pixels (default: 800)" },
      height: { type: "number", description: "Height in pixels (default: 600)" },
      storeBase64: { type: "boolean", description: "Store screenshot in base64 format (default: true)" },
      fullPage: { type: "boolean", description: "Store screenshot of the entire page (default: false)" },
      savePng: { type: "boolean", description: "Save screenshot as PNG file (default: false)" },
      downloadsDir: { type: "string", description: "Custom downloads directory path (default: user's Downloads folder)" },
    },
    required: ["name"],
  },
},

src/tools.ts:450-452 (helper)
The tool is listed in BROWSER_TOOLS array, used to conditionally launch browser before execution.
```
export const BROWSER_TOOLS = [
  "playwright_navigate",
  "playwright_screenshot",
```

mcp-playwright