Bug: --viewport option and resize_page tool fail in headless mode with Browser.setContentsSize error

[cycling777]

Bug Report: --viewport option and resize_page tool fail in headless mode

Environment

• chrome-devtools-mcp version: 0.5.1 (latest)
• Chrome version: 139.0.7258.138
• OS: Ubuntu 22.04.5 LTS
• Configuration: --headless=true --isolated=true --viewport=1280x720

Description

The --viewport option causes all MCP tools to fail with a protocol error in headless mode. The resize_page tool also fails with the same error.

Steps to Reproduce

1. Configure .mcp.json with --viewport=1280x720:

{
  "chrome-devtools": {
    "command": "npx",
    "args": [
      "chrome-devtools-mcp@latest",
      "--channel=stable",
      "--headless=true",
      "--isolated=true",
      "--viewport=1280x720"
    ]
  }
}

2. Restart MCP server
3. Try to use any tool (e.g., list_pages, navigate_page, or resize_page)

Expected Behavior

• --viewport option should set the initial viewport size
• resize_page tool should resize the page viewport
• All other tools should work normally

Actual Behavior

All tools fail with the error:

Protocol error (Browser.setContentsSize): 'Browser.setContentsSize' wasn't found

Root Cause Analysis

After investigating the source code, I found:

1. Both --viewport initialization and resize_page tool use page.resize() (marked as @ts-expect-error internal API for now)
2. This internal API calls Browser.setContentsSize from Chrome DevTools Protocol
3. Browser.setContentsSize is marked as Experimental in CDP and appears to be unavailable in headless mode

Source references:

• src/browser.ts: viewport initialization using page.resize()
• src/tools/pages.ts: resize_page tool using page.resize()

Suggested Solutions

Option 1: Use Emulation.setDeviceMetricsOverride
This is the standard CDP method for setting viewport size and works in headless mode:

await page._client().send('Emulation.setDeviceMetricsOverride', {
  width: options.viewport.width,
  height: options.viewport.height,
  deviceScaleFactor: 1,
  mobile: false,
});

Option 2: Document the limitation
If switching to Emulation.setDeviceMetricsOverride is not feasible, please:

• Add a note in the README that --viewport and resize_page don't work in headless mode
• Provide a workaround or alternative approach

Additional Context

• Without --viewport, the default viewport is 780x493
• This makes it difficult to capture screenshots at standard desktop resolutions (1280x720, 1920x1080, etc.)
• Other headless tools (Puppeteer, Playwright) successfully use Emulation.setDeviceMetricsOverride for viewport control

Related

• Chrome DevTools Protocol documentation: https://chromedevtools.github.io/devtools-protocol/tot/Browser#method-setContentsSize
• Browser.setContentsSize is marked as Experimental

[OrKoN]

Chrome 139 is not a current stable version. Could you please try with the current stable version which 141+?

[OrKoN]

Able to reproduce it with the latest version but somehow it was not caught in tests.

[cycling777]

Thank you for confirming the bug @OrKoN. I've upgraded Chrome from 139 to 141.0.7390.54 and can confirm the issue persists, though with different behavior.

Environment:

• Chrome version: 141.0.7390.54
• chrome-devtools-mcp: latest (npx chrome-devtools-mcp@latest)
• OS: Ubuntu 22.04.5 LTS
• Mode: --headless=true --viewport=1280x720

Test Results:

1. resize_page tool fails silently

   • Called resize_page({width: 1920, height: 1080})
   • Expected: viewport resized to 1920x1080
   • Actual: viewport remains 800x513 (no error thrown)
   • Verification: window.innerWidth=800, window.innerHeight=513

2. --viewport startup option also ignored

   • MCP server started with --viewport=1280x720
   • Expected: viewport initialized to 1280x720
   • Actual: viewport defaults to 800x600 (screen.width=800, screen.height=600)

Observation:
Unlike Chrome 139 which threw 'Browser.setContentsSize' wasn't found error, Chrome 141 fails silently - the tool returns success but the resize doesn't actually happen.

The root cause is likely the same (headless mode limitation), but the error handling differs between versions.