How to Screenshot a Website with an MCP Server and Custom Viewport Size

To screenshot a website at a custom size with Playwright MCP, set the server viewport using --viewport-size=1280x720 (replace those dimensions as needed), connect an MCP client, navigate to the page, and call browser_take_screenshot. This sets the browser’s visible page area. It does not set the height of a full-page screenshot.

1. Configure the custom viewport

Playwright MCP accepts a viewport size as WIDTHxHEIGHT. The documented example is 1280x720. Set it on the Playwright MCP server, not as a screenshot argument:

--viewport-size=1280x720

The equivalent environment variable is PLAYWRIGHT_MCP_VIEWPORT_SIZE. When a value is set in more than one place, command-line arguments take precedence over environment variables, which take precedence over the config file. Check all three locations if the browser opens at an unexpected size. See the official Playwright MCP configuration options.

Client-launched server

Configure the MCP client to launch @playwright/mcp with the viewport argument. The precise config-file shape depends on the client; the server argument is:

--viewport-size=1280x720

Keep the argument in the server’s argument list. If your client launches the server from an environment variable or config file instead, set PLAYWRIGHT_MCP_VIEWPORT_SIZE=1280x720 or the equivalent config option.

Standalone server over HTTP

You can also run the MCP server separately with HTTP transport and configure the MCP client to connect to its MCP endpoint. Start it with the desired viewport option, then connect the client and use its browser tools. The official Playwright MCP getting-started guide covers both client-launched and standalone HTTP arrangements.

2. Connect, navigate, and capture

Once connected, navigate to the target website with the browser navigation tool, then call browser_take_screenshot. Choose the capture scope to match what you need:

Capture scope	What it captures	Use it for
Viewport	The currently visible browser area at the configured viewport size	Consistent above-the-fold visual checks
Full page	The scrollable page, including content below the fold	Reviewing or documenting a long page
Element	A specific element, selected with an element reference or unique selector	Capturing a login form, card, or other component

For example, the screenshot tool accepts a full-page option or a target element. These are separate modes: do not combine fullPage: true with target.

// Current viewport
browser_take_screenshot({})

// Entire scrollable page
browser_take_screenshot({ fullPage: true })

// One element, using an element reference or unique selector
browser_take_screenshot({ target: "<element-reference-or-unique-selector>" })

Use an actual element reference returned by the browser tools or a selector that identifies one element on the page. A screenshot is for visual inspection. For reading page structure and finding element references, use the accessibility snapshot; it is designed for understanding and interacting with page content. See Playwright MCP screenshot documentation.

3. Choose image format and pixel scale

The screenshot tool supports PNG, JPEG, and WebP. It infers the format from the filename extension. If neither an explicit type nor a recognizable filename extension determines the format, PNG is used.

Option	Effect	Practical choice
PNG	Lossless image output	Useful when preserving crisp interface details matters
JPEG	Compressed image output	Useful when a smaller photographic image is preferable
WebP	Supported image output	Useful when your workflow accepts WebP
scale: "css"	Sizes output in CSS pixels; this is the default	Use for dimensions that match the page’s CSS layout
scale: "device"	Uses device-pixel ratio for the output image	Use when you need device-pixel-sized output

Set a filename extension that matches the format you want, or provide the screenshot tool’s supported type option. For scale, choose CSS pixels for layout comparisons across captures, or device pixels when the higher pixel density is needed. A custom viewport alone is not complete device emulation: it sets the visible width and height, but does not by itself configure all device characteristics.

4. Understand viewport size, full page, and device options

A viewport is the browser’s visible page area. For example, 1280x720 means a visible area 1280 CSS pixels wide and 720 CSS pixels high. A full-page screenshot is a separate capture mode that includes content below that visible area; its resulting image can therefore be taller than 720 pixels.

Playwright MCP also documents browser choices including Chrome (the default), Firefox, WebKit, and Microsoft Edge, plus device emulation options. Choose those separately when your workflow needs a different browser or device profile. Do not assume that changing only --viewport-size reproduces a phone or other device.

Playwright MCP runs headed by default. Add --headless to disable headed mode. This changes whether the browser UI is shown; it does not change the viewport dimensions.

5. Review the screenshot for visual checks

After capture, inspect the image for layout, spacing, clipping, and visual regressions. If the task is to read text or understand the page’s semantic structure, request an accessibility snapshot as well. Use that snapshot to locate elements and references, then take a targeted screenshot when only one component needs review.

6. Troubleshooting

Symptom	Likely cause	Fix
The browser opens at the default size	The viewport argument was not passed to the server, or a higher-precedence setting overrides it.	Confirm the server receives --viewport-size=WIDTHxHEIGHT. Check command-line arguments, environment variables, and config-file values in precedence order.
The viewport looks right, but the full-page image is much taller	Full-page mode captures content below the visible viewport.	This is expected. Use the default viewport screenshot for only the visible area.
The screenshot call rejects the options	Full-page capture and an element target were combined.	Call full-page mode without target, or omit full-page mode when capturing an element.
The output is PNG when another format was expected	The filename extension or explicit type did not identify JPEG or WebP.	Use a filename ending in .jpg or .webp, or set the supported type option.
Text or layout dimensions differ from expectations	The capture uses device-pixel scale, or viewport size was mistaken for device emulation.	Use scale: "css" for CSS-pixel dimensions. Configure device emulation separately if needed.
A target element is not found	The selector is not unique, the page has not navigated or rendered yet, or no valid element reference was supplied.	Inspect the page with an accessibility snapshot, use the resulting element reference, or choose a unique selector after navigation.
The client cannot connect to the server	The client and server are configured for different launch or transport arrangements.	Choose either a client-launched server or a standalone HTTP server and configure the client to match. Follow the official getting-started guide for that arrangement.

7. Performance, reliability, and cost considerations

The research sources do not publish comparable capture-speed or reliability benchmarks, so there is no supported timing figure to plan around. Full-page captures include more page content than viewport captures, and device-pixel scale can produce larger pixel dimensions; use the smallest capture scope and scale that answers the review question.

For repeatable visual review, keep the viewport, browser choice, capture scope, and scale consistent across runs. Dynamic pages can change between captures; use the page’s normal readiness and interaction workflow before taking the screenshot. The cited Playwright MCP material does not specify a price for Playwright MCP, so check the project’s current distribution and hosting requirements for your setup.

If enabling the optional ability to run Playwright code through the server, follow the official warning: “This tool runs arbitrary JavaScript in the Playwright server process and is RCE-equivalent — only enable for trusted MCP clients.” See the Playwright MCP getting-started documentation.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. Make one GET request with a URL to receive a PNG, JPEG, WebP, or PDF. The service can also take screenshots through an MCP server, including for AI agents using Claude, Cursor, or any MCP client.

Cookie banners are accepted like a visitor, and 60+ known consent platforms, newsletter popups, and chat widgets are removed before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. There are 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots.

Use this cURL request to save a WebP screenshot:

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

Python:

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)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

See the ScreenshotNeo API documentation for the endpoint and supported options. Create an account to get 1,000 free screenshots a month with no card.

FAQ

Does a 1280×720 viewport force every screenshot to be 1280×720 pixels?

It sets the visible browser area. Output pixel dimensions also depend on capture scope and whether CSS-pixel or device-pixel scale is used.

Can I use a custom viewport and full-page capture together?

Yes. The viewport sets the browser’s visible area while fullPage: true captures the scrollable page beyond it.

Should I use a screenshot or an accessibility snapshot to find text?

Use an accessibility snapshot to read structure and locate elements. Use screenshots to inspect visual appearance.

Does the viewport flag emulate a mobile device?

No. It sets width and height. Device emulation is a separate configuration choice.