ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use an MCP Server to Take Website Screenshots on Mobile Viewports

Configure Playwright MCP for a mobile device or viewport, capture the visible page or full page, and choose the right format and scale.

By the ScreenshotNeo team4 October 20269 min read

To take a website screenshot on a mobile viewport with an MCP server, connect Playwright MCP to your MCP client, start it with a mobile device profile or explicit viewport dimensions, navigate to the URL, then call browser_take_screenshot. Use fullPage: true for the entire scrollable page, or leave it unset for the currently visible viewport. This is browser emulation: it does not prove that the page was tested on a physical phone.

This guide uses the official Playwright MCP. Its documented mobile presets, browser options, and screenshot parameters are described in the configuration reference and screenshot tool reference.

1. Connect Playwright MCP to your client

Add a server entry to your MCP client’s configuration. The exact file and reload steps depend on the client; follow that client’s instructions for registering MCP servers.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--device=iPhone 15"]
    }
  }
}

The example asks npx to run the Playwright MCP package and configures an iPhone 15 emulation profile. Once the client has loaded the server, its browser tools should be available to the assistant. If the client does not expose them, check its MCP server status and configuration path, then restart or reload the client as its documentation specifies.

2. Choose how to emulate the mobile viewport

Set the mobile context when starting the MCP server. Choose a device preset when you want a documented device profile, generic mobile emulation for a quick mobile context, or explicit dimensions when you need a particular viewport width and height.

Choice Example argument Use it when
Named device --device="iPhone 15" You want a supported device emulation preset.
Generic mobile --mobile You want the documented generic mobile profile. The profile is Pixel 10 on Chromium and iPhone 17 on WebKit.
Explicit viewport --viewport-size="390x844" You need control of viewport width and height. Treat these as example dimensions, not a universal phone size.

The generic profile varies by browser engine. To make the setup reproducible, specify both the engine and mobile configuration when engine-specific behavior matters. The documented browser choices are Chrome (the default), Firefox, WebKit, and Microsoft Edge. Device profiles are emulations, not evidence of a physical-device test.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser=webkit", "--mobile"]
    }
  }
}

For a fixed viewport rather than a device preset, replace the arguments with ["@playwright/mcp@latest", "--browser=chromium", "--viewport-size=390x844"]. Use the engine name supported by the current configuration reference; its listed values include chrome, firefox, webkit, and msedge.

3. Navigate and capture

After the client connects, ask the assistant to navigate to the page and capture it. For example:

Navigate to https://example.com and take a screenshot of the current mobile viewport.

The corresponding MCP workflow is to call browser_navigate with the URL, then browser_take_screenshot. The MCP tool call can be expressed as:

browser_navigate({ "url": "https://example.com" })
browser_take_screenshot({
  "filename": "example-mobile.png",
  "type": "png",
  "fullPage": false,
  "scale": "css"
})

The tool returns the screenshot inline to the client and saves it at the requested filename. A relative filename resolves against the workspace root. If you omit the filename, Playwright MCP chooses a timestamped name in its output directory and returns the image inline.

4. Pick capture scope, format, and resolution

Parameter Options and behavior Practical choice
target Optional element reference or selector; captures one element. Use for a component such as a mobile navigation menu or product card.
fullPage Optional boolean; captures the full scrollable page instead of the viewport. Set to true for a long page. It cannot be combined with target.
type png, jpeg, or webp. Choose explicitly for predictable output. If omitted, the filename extension is used; otherwise the default is PNG.
filename Optional output path. Use a descriptive path in your workspace if you need a durable artifact.
scale css (default) or device. css produces CSS-pixel sizing; device uses the device pixel ratio for a higher-resolution image.

Examples of valid requests:

// Current mobile viewport, CSS-pixel sizing
browser_take_screenshot({ "filename": "viewport.webp", "type": "webp", "scale": "css" })

// Full scrollable page
browser_take_screenshot({ "filename": "full-page.png", "fullPage": true })

// One element, identified by a fresh snapshot reference or selector
browser_take_screenshot({ "target": "e12", "filename": "menu.png" })

// Higher-resolution output using device pixel ratio
browser_take_screenshot({ "filename": "retina.jpeg", "type": "jpeg", "scale": "device" })

Do not combine target and fullPage: true. For an element reference such as e12, first obtain a current accessibility snapshot. References are tied to the snapshot and can become invalid after navigation or page changes.

5. Use screenshots and accessibility snapshots together

A screenshot is useful for visual layout, image and canvas content, and documenting a bug. It is not the best source of structured page text or stable element references. Use browser_snapshot to inspect accessibility structure and identify elements for interaction; then use a screenshot to check how those elements look. Playwright’s documentation summarizes the distinction on its screenshots page and snapshots page.

  1. Navigate to the page in the desired mobile context.
  2. Request a fresh accessibility snapshot to inspect the page and locate a control.
  3. Use the snapshot reference to interact with the control, if needed.
  4. Take a screenshot to inspect the resulting visual state.
  5. After a navigation or other page change, refresh the snapshot before relying on old references.

For bug reports, record the URL, browser engine, device preset or viewport dimensions, and whether the image is viewport-only or full-page. Describe the result as an emulated browser capture unless a real device was independently tested.

6. Useful configuration options

Playwright MCP accepts settings through a configuration file, environment variables, and command-line arguments, with command-line arguments taking precedence over environment variables and the config file. The following options can matter for mobile screenshot work:

Option When it helps
--browser Select chrome, firefox, webkit, or msedge when the engine is part of the reproduction.
--device Use a named device emulation profile, such as iPhone 15.
--mobile Enable the documented generic mobile emulation profile.
--viewport-size Set explicit width and height, written as WIDTHxHEIGHT.
--user-agent Set a custom user-agent string if a specific user-agent-dependent issue must be reproduced. A user-agent string alone does not make a desktop context a complete device emulation.
--headless Run without a visible browser window; the documented default is headed mode.
--executable-path Use a particular browser executable where your environment requires one.
--ignore-https-errors Ignore HTTPS errors for a controlled debugging case; avoid using it to conceal certificate problems in a normal reproduction.
--proxy-server and --proxy-bypass Route requests through a proxy or exclude selected hosts when your network requires it.

For example, a headless WebKit mobile setup could use ["@playwright/mcp@latest", "--browser=webkit", "--mobile", "--headless"]. Use npx @playwright/mcp@latest --help and the linked official configuration reference to confirm current options in your installed package.

7. Troubleshooting

Symptom Likely cause Fix
The client cannot see Playwright tools. The MCP entry is in the wrong client config, has invalid JSON, or the client has not reloaded it. Validate the configuration, check the client’s MCP status or logs, and reload or restart the client according to its documentation.
npx or package launch fails. Node.js/npm is unavailable, package retrieval is blocked, or the execution environment cannot launch child processes. Check that Node.js and npm are installed and available to the client process; resolve network or execution restrictions, then retry.
The page looks desktop-sized. The mobile option was not applied, the server was not restarted after changing its arguments, or a fixed viewport was configured. Inspect the effective server arguments, restart the MCP server, and use a device profile, --mobile, or explicit mobile dimensions.
The generic mobile result differs by browser. The generic preset is documented as Pixel 10 on Chromium and iPhone 17 on WebKit. Pin the browser engine and choose a named device or explicit dimensions for a reproducible comparison.
A target reference such as e12 is missing or selects the wrong element. The reference came from an old accessibility snapshot or the page changed. Take a fresh browser_snapshot, identify the element again, and retry. A selector can also be used as the target.
A request combines element and full-page capture. fullPage and target are incompatible. Choose one scope: capture a target element, or capture the full scrollable page.
The image is unexpectedly large or small. The requested scale differs from the intended CSS-pixel or device-pixel output. Set scale: "css" for CSS-pixel sizing or scale: "device" for a higher-resolution image based on device pixel ratio.
The file is saved with an unexpected format. The type was inferred from the extension or defaulted to PNG. Set both type and a matching filename extension explicitly.
Full-page capture misses content that appears only after scrolling. The page may load content lazily or depend on scroll-triggered behavior. Scroll through the page before capturing, wait for the relevant content, and capture again. Verify the final image rather than assuming all dynamic content loaded.
The screenshot does not match a physical phone. Browser emulation is not a physical-device run and may not reproduce every hardware, browser, or network condition. State the emulated engine and viewport in the report. Validate on the target physical device when hardware-specific behavior is the issue.

8. Performance, reliability, and cost

Playwright MCP runs a browser session, so capture time includes launching or reusing that browser, loading the page and its resources, and producing the image. Large full-page captures and device-scale output can create larger images and take more work to inspect or transfer. For repeated visual checks, use a consistent engine, profile, viewport, scope, and scale so changes in the output have a clear cause.

Page variability also affects reproducibility: network conditions, dynamic content, animations, and scroll-triggered loading can change what appears. Re-capture when the page has reached the intended state, and record the context needed to reproduce it. Browser emulation is useful for development review, but it should not be described as physical handset validation.

The Playwright MCP package is launched through npx; the cited documentation does not establish a per-screenshot service price. Operational cost depends on the environment running the browser, such as your own machine or an MCP-hosting setup. Account for browser runtime and image storage or transfer in that environment rather than assuming a hosted screenshot API billing model.

9. Or skip the browser setup

If you need a screenshot endpoint instead of managing an MCP browser session, ScreenshotNeo is a website screenshot API and MCP server. Its MCP tools include take_screenshot, get_page_info, and capture_pdf. For a straightforward API capture, make one GET request with the target URL. See the ScreenshotNeo API documentation for request options, including viewport and device settings.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
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', res);

Replace YOUR_API_KEY with your key and change the target URL as needed. The Node.js example uses Bun’s Bun.write to save the response; in Node.js, use await import('node:fs/promises').then(({writeFile}) => writeFile('shot.webp', Buffer.from(await res.arrayBuffer()))) after checking the response status.

  • Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
  • Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are never billed. Response headers identify the page verdict and billing status.
  • An MCP server lets AI agents, including Claude, Cursor, and other MCP clients, take screenshots.
  • The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots.

Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.

10. Frequently asked questions

Does a mobile viewport screenshot prove the page works on a real phone?

No. It documents a browser emulation configured with a particular engine and profile or viewport. Use a physical device for hardware-specific validation.

Should I use a device preset or fixed dimensions?

Use a preset when you want a device emulation profile. Use dimensions when the exact width and height are the requirement or when you need repeatable viewport comparisons.

Can I capture only the visible screen?

Yes. Leave fullPage unset or false and do not specify a target. The tool captures the current viewport.

What should I use to locate an element?

Use an accessibility snapshot for page structure and current element references. Screenshots help verify appearance; they are not the source of stable interaction references.

Can I use this workflow for a mobile screenshot of every URL in a list?

The documented MCP workflow captures pages through browser navigation and tool calls. For a larger URL set, consider automating the calls in your client or using a screenshot API with bulk capture support.

Keep reading