feat: add default screenshot format configuration and update related functionality

Author: marcandreuf

README.md

@@ -383,6 +383,12 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `true`
 
+- **`--screenshot-format`**
+  Default image format for screenshots. Options: png, jpeg, webp. Default is png.
+  - **Type:** string
+  - **Choices:** `png`, `jpeg`, `webp`
+  - **Default:** `png`
+
 <!-- END AUTO GENERATED OPTIONS -->
 
 Pass them via the `args` property in the JSON configuration. For example:
@@ -424,6 +430,36 @@ You can connect directly to a Chrome WebSocket endpoint and include custom heade
 
 To get the WebSocket endpoint from a running Chrome instance, visit `http://127.0.0.1:9222/json/version` and look for the `webSocketDebuggerUrl` field.
 
+### Configuring default screenshot format
+
+You can set a default image format for all screenshots using the `--screenshot-format` option. The default is PNG. You can change it to JPEG or WebP if needed:
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--screenshot-format=jpeg"
+      ]
+    }
+  }
+}
+```
+
+When configured, the `take_screenshot` tool will use this format by default unless explicitly overridden by passing a `format` parameter. Supported formats are `png`, `jpeg`, and `webp`.
+
+> [!TIP]
+> PNG is the default format as it provides lossless screenshots. JPEG typically produces smaller file sizes than PNG, which improves performance when working with screenshots. WebP offers the best compression while maintaining quality.
+
+> [!NOTE]
+> **Claude Code users**: If you experience issues with screenshots not displaying correctly, you can work around this by:
+> 1. Setting the default format to JPEG in your configuration (recommended): Add `--screenshot-format=jpeg` to your MCP server args
+> 2. Explicitly passing `jpeg` as the format parameter in all `take_screenshot()` calls: `take_screenshot(format="jpeg")`
+>
+> This workaround is needed until the issue is resolved on Claude Code's side.
+
 You can also run `npx chrome-devtools-mcp@latest --help` to see all available configuration options.
 
 ## Concepts

src/McpContext.ts

@@ -49,6 +49,8 @@ interface McpContextOptions {
   experimentalDevToolsDebugging: boolean;
   // Whether all page-like targets are exposed as pages.
   experimentalIncludeAllPages?: boolean;
+  // Default screenshot format.
+  screenshotFormat?: 'png' | 'jpeg' | 'webp';
 }
 
 const DEFAULT_TIMEOUT = 5_000;
@@ -292,6 +294,10 @@ export class McpContext implements Context {
     this.#dialog = undefined;
   }
 
+  getDefaultScreenshotFormat(): 'png' | 'jpeg' | 'webp' {
+    return this.#options.screenshotFormat ?? 'png';
+  }
+
   getSelectedPage(): Page {
     const page = this.#selectedPage;
     if (!page) {

src/cli.ts

@@ -160,6 +160,13 @@ export const cliOptions = {
     default: true,
     describe: 'Set to false to exclude tools related to network.',
   },
+  screenshotFormat: {
+    type: 'string',
+    describe:
+      'Default image format for screenshots. Options: png, jpeg, webp. Default is png.',
+    choices: ['png', 'jpeg', 'webp'] as const,
+    default: 'png',
+  },
 } satisfies Record<string, YargsOptions>;
 
 export function parseArguments(version: string, argv = process.argv) {
@@ -212,6 +219,10 @@ export function parseArguments(version: string, argv = process.argv) {
         'Disable tools in the performance category',
       ],
       ['$0 --no-category-network', 'Disable tools in the network category'],
+      [
+        '$0 --screenshot-format jpeg',
+        'Set default screenshot format to JPEG (overrides PNG default)',
+      ],
     ]);
 
   return yargsInstance

src/main.ts

@@ -86,6 +86,7 @@ async function getContext(): Promise<McpContext> {
     context = await McpContext.from(browser, logger, {
       experimentalDevToolsDebugging: devtools,
       experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+      screenshotFormat: args.screenshotFormat as 'png' | 'jpeg' | 'webp',
     });
   }
   return context;

src/tools/ToolDefinition.ts

@@ -120,6 +120,10 @@ export type Context = Readonly<{
    * Returns a reqid for a cdpRequestId.
    */
   resolveCdpElementId(cdpBackendNodeId: number): string | undefined;
+  /**
+   * Returns the configured default screenshot format.
+   */
+  getDefaultScreenshotFormat(): 'png' | 'jpeg' | 'webp';
 }>;
 
 export function defineTool<Schema extends zod.ZodRawShape>(

src/tools/screenshot.ts

@@ -21,8 +21,8 @@ export const screenshot = defineTool({
   schema: {
     format: zod
       .enum(['png', 'jpeg', 'webp'])
-      .default('png')
-      .describe('Type of format to save the screenshot as. Default is "png"'),
+      .optional()
+      .describe('Type of format to save the screenshot as. If not specified, uses the configured default format.'),
     quality: zod
       .number()
       .min(0)
@@ -62,8 +62,11 @@ export const screenshot = defineTool({
       pageOrHandle = context.getSelectedPage();
     }
 
+    // Use configured default format if not specified in request
+    const format = request.params.format ?? context.getDefaultScreenshotFormat();
+
     const screenshot = await pageOrHandle.screenshot({
-      type: request.params.format,
+      type: format,
       fullPage: request.params.fullPage,
       quality: request.params.quality,
       optimizeForSpeed: true, // Bonus: optimize encoding for speed
@@ -89,12 +92,12 @@ export const screenshot = defineTool({
     } else if (screenshot.length >= 2_000_000) {
       const {filename} = await context.saveTemporaryFile(
         screenshot,
-        `image/${request.params.format}`,
+        `image/${format}`,
       );
       response.appendResponseLine(`Saved screenshot to ${filename}.`);
     } else {
       response.attachImage({
-        mimeType: `image/${request.params.format}`,
+        mimeType: `image/${format}`,
         data: Buffer.from(screenshot).toString('base64'),
       });
     }

tests/cli.test.ts

@@ -16,6 +16,8 @@ describe('cli args parsing', () => {
     categoryPerformance: true,
     'category-network': true,
     categoryNetwork: true,
+    'screenshot-format': 'png',
+    screenshotFormat: 'png',
   };
 
   it('parses with default args', async () => {