How to Capture Screenshots with Playwright MCP

Use Playwright MCP’s browser_take_screenshot tool after navigating to the page you want to capture. With no target, it captures the current viewport. Set target to an element reference or unique selector to capture one element, or set fullPage: true to capture the scrollable page. A full-page capture cannot be combined with target.

1. Set up the Playwright MCP server

If you already have a Playwright MCP server connected to your MCP client, skip to the capture steps. For a standalone server, the official getting-started guide uses this command:

npx @playwright/mcp@latest --port 8931

Configure your MCP client to connect to http://localhost:8931/mcp. The exact location and format of the server configuration depend on the client, so use that client’s MCP setup instructions. Keep the server running while you send tool requests.

2. Navigate to the page

Use the browser navigation tool provided by your connected Playwright MCP server to open the page first. Then call browser_take_screenshot. The screenshot tool captures the page that is currently open; it does not navigate to a URL by itself.

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

Current viewport

Call the tool without a target or fullPage option to capture the visible viewport:

browser_take_screenshot {}

You can supply a filename and scale when you need a saved file or a specific pixel density:

browser_take_screenshot {
  filename: "homepage.png",
  scale: "css"
}

One element

To capture a specific element, first use an accessibility snapshot to locate it and obtain a reference, or identify it with a unique selector. Pass that reference or selector as target:

browser_take_screenshot {
  target: "ref from the accessibility snapshot",
  filename: "pricing-card.png"
}

The target should identify the element you intend to capture. If a selector matches multiple elements or the element is not present, refine the selector or take a fresh snapshot and use the correct reference.

Full scrollable page

Set fullPage to true to include content below the fold:

browser_take_screenshot {
  fullPage: true,
  filename: "homepage.png"
}

Do not combine fullPage: true with target. Choose one-element capture or full-page capture for a request.

4. Choose the file format, filename, and scale

Option	Behavior	When to use it
filename	Saves the screenshot. Relative paths resolve against the workspace root. If omitted, the tool returns the image inline using a generated filename in its output directory.	Set it when a later workflow needs a predictable file path; omit it when you want to inspect the returned image directly.
type	Accepts png, jpeg, or webp. If unset, the extension in filename determines the type. With no extension to infer from, PNG is the default.	Choose an explicit type when the filename does not establish the intended format.
scale	Defaults to css, which uses CSS-pixel sizing. Set it to device for a higher-resolution capture based on the device pixel ratio.	Use CSS scale for CSS-pixel dimensions; use device scale when device-pixel detail matters.

For example, explicitly request WebP output and device-pixel resolution:

browser_take_screenshot {
  filename: "homepage.webp",
  type: "webp",
  scale: "device"
}

The documented formats are PNG, JPEG, and WebP. Match the extension and type if you set both, so the saved file’s name reflects its format.

5. Use the right result for visual inspection or interaction

A screenshot is useful for checking visual layout, viewing charts or canvas content, and documenting a visual issue. Use an accessibility snapshot to read page structure, find elements, and obtain references for interaction. Playwright’s guidance is to use screenshots for looking at the page and browser_snapshot to get references to interact with it. Do not base browser actions solely on pixels when a structural snapshot can identify the target.

6. Troubleshooting

Symptom	Likely cause	Fix
The screenshot shows the previous page or an empty page.	Navigation did not finish, or the intended page was not opened in the active browser session.	Navigate to the page in the connected session, confirm it is open, and call the screenshot tool again.
The full-page request fails or does not behave as expected with a target.	fullPage and target were supplied together.	Remove target for a full-page capture, or remove fullPage to capture one element.
The image is saved somewhere unexpected.	A relative filename is resolved from the workspace root.	Use a path relative to that root or specify a suitable path for the workspace.
The file is PNG when another format was expected.	No supported extension was available to infer the format, and no explicit type was supplied.	Set type to jpeg or webp, or use a filename with the intended extension.
An element capture cannot find the intended content.	The reference came from an old snapshot, the selector is not unique, or the element is absent.	Take a fresh accessibility snapshot, confirm the element, and use its current reference or a unique selector.
The output looks less detailed than expected.	The default scale: "css" captures at CSS-pixel sizing.	Set scale: "device" when a higher-resolution, device-pixel capture is needed.
The MCP client cannot connect to the server.	The standalone server may not be running, or the client endpoint may not match its configured address.	Start the server with the documented command and check that the client connects to http://localhost:8931/mcp.

7. Performance, reliability, and cost considerations

The documented options describe capture scope, file handling, and image scale; the research does not establish performance benchmarks. A full-page image includes more page content than a viewport capture, while device scale produces higher-resolution output than CSS scale. Select the smallest scope and resolution that meet the task, especially when storing or passing images through another tool.

Capture reliability depends on having the intended page open in the active browser session and choosing a valid target when requesting an element. For repeatable workflows, use a predictable filename and explicitly set the output type and scale. The cited Playwright setup and screenshot documentation do not specify a price; any hosting or usage cost depends on the environment in which you run the server.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a screenshot or PDF, and its MCP tools include take_screenshot, get_page_info, and capture_pdf. The API accepts familiar screenshot parameter names, which can make switching easier. See the ScreenshotNeo API documentation.

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}`);

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. AI agents can use its MCP server. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month, no card required.

9. FAQ

What is the Playwright MCP screenshot tool called?

browser_take_screenshot.

Does omitting filename discard the image?

No. The tool returns the image inline and uses a generated filename in its output directory.

Can I capture a full page and a selected element in one call?

No. fullPage: true cannot be combined with target.

Should I use a screenshot to find an element to click?

Use an accessibility snapshot to inspect structure and obtain interaction references. A screenshot is for visual inspection.