Playwright MCP Server

Instructions

Implementation Reference

• src/toolsHandler.ts:90-174 (handler)

  Main execution logic for the playwright_screenshot tool. Captures screenshot of page or element, optionally saves as PNG file and/or stores base64 image as a server resource.

  case "playwright_screenshot": {
    try {
      const screenshotOptions: any = {
        type: args.type || "png",
        fullPage: !!args.fullPage
      };
  
      if (args.selector) {
        const element = await page!.$(args.selector);
        if (!element) {
          return {
            toolResult: {
              content: [{
                type: "text",
                text: `Element not found: ${args.selector}`,
              }],
              isError: true,
            },
          };
        }
        screenshotOptions.element = element;
      }
  
      if (args.mask) {
        screenshotOptions.mask = await Promise.all(
          args.mask.map(async (selector: string) => await page!.$(selector))
        );
      }
  
      const screenshot = await page!.screenshot(screenshotOptions);
      const base64Screenshot = screenshot.toString('base64');
  
      const responseContent: (TextContent | ImageContent)[] = [];
  
      // Handle PNG file saving
      if (args.savePng !== false) {
        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
        const filename = `${args.name}-${timestamp}.png`;
        const downloadsDir = args.downloadsDir || defaultDownloadsPath;
  
        // Create downloads directory if it doesn't exist
        if (!fs.existsSync(downloadsDir)) {
          fs.mkdirSync(downloadsDir, { recursive: true });
        }
  
        const filePath = path.join(downloadsDir, filename);
        await fs.promises.writeFile(filePath, screenshot);
        responseContent.push({
          type: "text",
          text: `Screenshot saved to: ${filePath}`,
        } as TextContent);
      }
  
      // Handle base64 storage
      if (args.storeBase64 !== false) {
        screenshots.set(args.name, base64Screenshot);
        server.notification({
          method: "notifications/resources/list_changed",
        });
  
        responseContent.push({
          type: "image",
          data: base64Screenshot,
          mimeType: "image/png",
        } as ImageContent);
      }
  
      return {
        toolResult: {
          content: responseContent,
          isError: false,
        },
      };
    } catch (error) {
      return {
        toolResult: {
          content: [{
            type: "text",
            text: `Screenshot failed: ${(error as Error).message}`,
          }],
          isError: true,
        },
      };
    }
  }

• src/tools.ts:16-32 (schema)

  Tool schema definition including name, description, and input schema with properties for screenshot options.

  {
    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)" },
        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/requestHandler.ts:59-62 (registration)

  Registration of the listTools request handler which returns the array of all tools including playwright_screenshot schema.

  // List tools handler
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: tools,
  }));

• src/requestHandler.ts:64-67 (registration)

  Registration of the callTool request handler which routes tool calls to handleToolCall including for playwright_screenshot.

  // Call tool handler
  server.setRequestHandler(CallToolRequestSchema, async (request) =>
    handleToolCall(request.params.name, request.params.arguments ?? {}, server)
  );

• src/tools.ts:152-160 (helper)

  Helper constant listing tools that require a browser instance, used to conditionally launch Chromium before executing playwright_screenshot.

  export const BROWSER_TOOLS = [
    "playwright_navigate",
    "playwright_screenshot",
    "playwright_click",
    "playwright_fill",
    "playwright_select",
    "playwright_hover",
    "playwright_evaluate"
  ];