ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Capture a Mobile-Width Website Screenshot Through MCP

Set a mobile viewport in Playwright MCP, choose what to capture, and save a screenshot. Includes device emulation, options, troubleshooting, and an API shortcut.

By the ScreenshotNeo team4 October 20267 min read

To capture a mobile-width website screenshot through Playwright MCP, set the browser viewport to the width and height you want, navigate to the page, then call browser_take_screenshot. For example, resize to 375 × 812 CSS pixels and capture the visible viewport. Use fullPage: true for the full scrollable page or target for one element. Choose a named or generic mobile device profile when you also need device emulation; use explicit dimensions when you need exact control over the responsive breakpoint.

This guide uses Playwright MCP’s documented tools and configuration. See the official configuration options, interaction guide, and screenshot tool reference.

1. Choose a viewport or device profile

These choices answer different questions:

Approach Use it when What to know
Explicit viewport You are checking a responsive breakpoint or need reproducible width and height. Set width and height in CSS pixels. The interaction guide demonstrates 375 × 812 as an example, not as a universal mobile standard.
Named device You want a device preset, including its emulation settings. Configuration supports --device="iPhone 15". Device presets represent more than viewport width.
Generic mobile You want a generic mobile profile without specifying a named device. --mobile uses Pixel 10 on Chromium or iPhone 17 on WebKit in the current documentation. Do not combine it with --device.

If your question is “does this layout change at 390 CSS pixels?”, set the viewport explicitly. If you are checking a device-like scenario, use a device preset and record which browser engine you used. A screenshot at a chosen width shows how the site rendered in that browser configuration; it does not guarantee every real device will render identically.

2. Set the viewport in an MCP session

You can start the MCP server with a viewport size, or resize an open page using the interaction tool. The exact server launch command depends on how your MCP client has installed and configured Playwright MCP; the relevant option is --viewport-size=<width>x<height>.

npx @playwright/mcp@latest --viewport-size=375x812

In an existing session, invoke the browser resize tool:

browser_resize({ width: 375, height: 812 })

Then navigate to the page with the browser navigation tool in your MCP client. For example, navigate to https://example.com, wait for the page to reach the state you want to inspect, and take the screenshot. Replace the example URL with your target. The dimensions above are a documented usage example; use dimensions appropriate to your own breakpoint or test case.

To use device emulation instead, configure the server with a supported device name, such as:

npx @playwright/mcp@latest --device="iPhone 15"

Or choose generic mobile mode:

npx @playwright/mcp@latest --mobile

Consult the official configuration reference for the current supported options and device names. Do not combine --mobile with --device.

3. Capture the viewport, an element, or the full page

Once the browser is at the desired URL and state, call browser_take_screenshot. The main choice is the capture area:

Capture Options Result
Visible viewport Leave target and fullPage unset. The currently visible area at the configured viewport dimensions.
One element Set target to an element reference or selector. A screenshot limited to that element.
Full scrollable page Set fullPage: true. A capture of the full page, including content beyond the viewport.

fullPage cannot be combined with target. A full-page capture is useful for reviewing all content, but it is no longer a screenshot of only the initial mobile viewport. For a breakpoint check, capture the viewport first; take a separate full-page screenshot if you also need to inspect below the fold.

A typical tool call can specify the output type, filename, and scale as well:

browser_take_screenshot({
  filename: "mobile-homepage.png",
  type: "png",
  scale: "css"
})

The tool call above assumes the browser has already been resized and navigated. Tool schemas can vary by MCP client version, so use the installed server’s tool definition when supplying arguments.

4. Choose output format, scale, and filename

  • type: PNG, JPEG, or WebP. If omitted, the type is inferred from the filename extension or defaults to PNG.
  • scale: "css" is the default and produces an image sized in CSS pixels. "device" uses device pixels, producing a higher-resolution image based on device pixel ratio.
  • filename: choose a name to save the screenshot. If omitted, the screenshot is returned inline and a default filename is used in the output directory.

Use PNG when crisp edges and text matter or when you need lossless output. JPEG can be suitable for photographic pages when a smaller lossy image is acceptable. WebP is another supported output choice. Use CSS scale to compare layout dimensions consistently; device scale is useful when you need the pixel density represented by the emulated device. Larger pixel dimensions can increase image size and the work needed to store or inspect the result.

5. Use screenshots for visuals and snapshots for page structure

A screenshot is useful for visual review: layout, colors, charts, canvas output, and responsive composition. It is not the best way to identify controls for subsequent interaction. Playwright MCP recommends accessibility snapshots for page structure and interaction. Use browser_snapshot to inspect accessible elements and get references to act on. Optional bounding boxes in snapshots are relative to the viewport and measured in CSS pixels.

In practice, use this sequence when you need both inspection and interaction:

  1. Set the viewport or device profile.
  2. Navigate and inspect the page with an accessibility snapshot.
  3. Use snapshot references to interact with the page or reach the desired state.
  4. Call browser_take_screenshot to review the resulting appearance.

As the official screenshot documentation puts it, screenshots are “for looking at, not for acting on.” See Playwright MCP snapshots for the structure and interaction workflow.

6. Troubleshooting

Symptom Likely cause Fix
The page looks like desktop despite a narrow screenshot. The viewport was resized after navigation or the page has not reacted to the resize yet. Resize the page, wait for responsive layout changes, then capture. Confirm the configured width rather than relying on the image’s apparent dimensions.
The screenshot includes only the top portion of a long page. The default capture is the visible viewport. Use fullPage: true when you need the entire scrollable page. Do not combine it with target.
The screenshot is unexpectedly large or small in pixels. scale controls CSS-pixel versus device-pixel output. Set scale: "css" for CSS-sized output or scale: "device" for device-pixel output.
A tool cannot find a control from the screenshot. A screenshot is visual output and does not provide the structural references used for actions. Take an accessibility snapshot and use its element references for interaction.
The device option and mobile option conflict. Generic --mobile cannot be combined with --device. Choose one profile. For exact dimensions, use --viewport-size or browser_resize.
The captured content differs between runs. The page may still be loading or may have time-dependent content. Wait for the page to reach the state you intend to capture, then take the screenshot. Use the same viewport, browser engine, and device configuration when comparing runs.
The format does not match the intended output. The type may be inferred from the filename, or default to PNG. Set type explicitly, or make the filename extension match the desired type.

7. Performance, reliability, and cost

For repeatable visual checks, keep the viewport dimensions, browser engine, device profile, capture scope, and scale consistent. A viewport screenshot generally limits the output to the visible area; full-page screenshots include more content and can take more work to render and inspect. Device-pixel scale can produce larger images than CSS-pixel scale. The Playwright MCP documentation does not promise that a specific site will load or render correctly at any selected size, so wait for the page state you need and review the output.

Playwright MCP is a browser automation workflow: you configure and run the browser MCP server, then ask your MCP client to navigate, resize, and capture. The tool documentation does not specify a per-screenshot price. Your costs depend on your browser hosting and MCP environment.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. For this task, you can request a mobile viewport in one API call:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com --data-urlencode width=375 --data-urlencode height=812 -o shot.webp

See the ScreenshotNeo API documentation for request options and setup. Here are equivalent Python and Node.js requests:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={
        "access_key": "YOUR_API_KEY",
        "url": "https://stripe.com",
        "width": 375,
        "height": 812,
    },
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
  width: '375',
  height: '812'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', await res.arrayBuffer());

These examples use the API’s width and height parameters for the mobile viewport. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is available on every plan.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Is 375 × 812 the standard mobile viewport?

No. It is an example size in the Playwright MCP interaction guide. Choose dimensions that match the breakpoint or device scenario you want to evaluate.

Should I use a screenshot or an accessibility snapshot?

Use a screenshot to review visual appearance. Use an accessibility snapshot to inspect structure and find elements for interaction.

Does a mobile device preset only change the viewport?

No. A device profile emulates more than width. For a specific responsive-width check, set explicit dimensions.

Can I capture one element and the full page in the same call?

No. Playwright MCP documents that target and fullPage cannot be combined. Make separate captures for those needs.

Keep reading