Keyword: playwright mcp screenshot · Updated October 15, 2026
Playwright MCP Screenshots: Where Files Go, Snapshot vs Screenshot Mode, and 5 Gotchas
You asked Claude, Cursor or Copilot to "take a screenshot of the page", the agent said it did, and now you cannot find the PNG. Or the agent keeps taking screenshots when it should be clicking, and your context window fills up with images. Both problems come from how Playwright MCP splits page reading into two tools. This guide covers what browser_take_screenshot does, where it writes files, and which flags change that.
The short answer
| Question | Answer |
|---|---|
| Can Playwright MCP take screenshots? | Yes, with browser_take_screenshot. It is a core tool, so you do not need --caps. |
| Where is the file saved? | No filename: the output directory, as page-{timestamp}.png. With a filename: relative to the workspace root. |
| How do I choose the folder? | --output-dir ./screenshots or PLAYWRIGHT_MCP_OUTPUT_DIR. |
| Full page? | fullPage: true, but not together with an element target. |
| Can the agent click based on the screenshot? | No. It clicks with refs from browser_snapshot. Coordinate clicks need --caps=vision. |
What browser_take_screenshot accepts
The parameter list is short. Most confusion comes from two of them: filename, which changes where the file lands, and scale, which defaults to something different from plain Playwright.
| Parameter | Type | What it does |
|---|---|---|
type | string | Image format: png, jpeg or webp. If unset, it is taken from the filename extension, otherwise PNG. |
filename | string | Where to save. A relative name resolves against the workspace root. If omitted, the file goes to the output directory as page-{timestamp}.{ext}. |
fullPage | boolean | Captures the full scrollable page instead of the viewport. Cannot be combined with an element screenshot. |
target | string | An element ref from the last snapshot (for example e42) or a unique selector. Crops the image to that element. |
element | string | A human-readable description of the element, used for the permission prompt. |
scale | "css" | "device" | css (the default here) keeps one image pixel per CSS pixel. device uses device pixels and produces larger, sharper images on high-DPI setups. |
A typical call from an agent looks like this:
You usually do not write this JSON yourself. You ask in plain language ("take a full-page screenshot and save it as screenshots/pricing-after-fix.png") and the agent fills the arguments. Naming the file in the prompt is the simplest way to know where it will land.
Where Playwright MCP saves screenshots
Google's suggestions for this tool are full of "location" and "folder" queries. The answer depends on one thing: whether the agent passed a filename.
| Call | Saved to | Affected by --output-dir? |
|---|---|---|
No filename | <output dir>/page-{timestamp}.png | Yes |
filename: "shot.png" | <workspace root>/shot.png | No |
filename: "qa/home.webp" | <workspace root>/qa/home.webp | No |
The README does not document a fixed default path for the output directory, so do not rely on one. If you need predictable file locations, set it yourself:
Two related options are worth knowing. --output-max-size sets a byte threshold after which old output files are evicted, so long sessions do not fill the disk. --file-paths absolute makes tool results print absolute paths instead of paths relative to the workspace root, which helps when the client runs in a different directory than you expect.
filename pointing outside that area will fail unless you start the server with --allow-unrestricted-file-access. Keep screenshots inside the project instead.Snapshot vs screenshot: which one the agent should call
Playwright MCP is built around the accessibility snapshot. browser_snapshot returns a structured tree of the page with a ref for each interactive element. The agent uses those refs in browser_click, browser_type and other actions. The screenshot tool's own description says the agent cannot perform actions based on the screenshot.
| Task | Use | Why |
|---|---|---|
| Find and click a button | browser_snapshot | Returns refs the click tool accepts. |
| Read text, check a form's labels | browser_snapshot | Text is cheaper than an image and exact. |
| Check layout, overlap, colors, broken images | browser_take_screenshot | Visual bugs do not show up in an accessibility tree. |
| Attach proof to a PR or ticket | browser_take_screenshot with filename | You get a file at a known path. |
| Click on a canvas or a map | --caps=vision + browser_mouse_click_xy | There is no ref to click, only coordinates. |
The --snapshot-mode flag controls whether the server attaches a snapshot to tool responses. The default is full. Setting it to none makes responses smaller, but the agent then has to call browser_snapshot explicitly before it can interact with anything. Use none only for screenshot-heavy sessions where the agent mostly navigates and captures.
If the agent needs element positions together with the tree, browser_snapshot accepts boxes: true (or start the server with --snapshot-boxes). Each element then carries [box=x,y,width,height] in CSS pixels, which is often enough to reason about layout without a single image.
5 gotchas that waste an afternoon
1. fullPage plus target returns an error
The tool documentation says fullPage cannot be used with element screenshots. If an agent asks for "the full pricing table, full page", it may send both and fail. Tell it which one you want: the whole page, or the element with ref e42.
2. Screenshots look smaller than in your Playwright tests
In the Playwright library, page.screenshot() defaults to scale: "device". In Playwright MCP the default is css. On a 2x display the same page produces an image half the width and height. That is intentional, because smaller images cost fewer tokens. Ask for scale: "device" when you need sharp text for a design review.
3. The headed browser window changes the result
Playwright MCP runs headed by default. If you resize the window, move it to another monitor or the OS scales it, viewport screenshots change size. Pin the viewport with --viewport-size 1280x720 and add --headless in CI or when you need reproducible captures.
4. Logged-in state leaks between sessions
By default the server uses a persistent profile, so cookies from yesterday's session are still there. That is convenient for authenticated pages and confusing for "what does a new visitor see" screenshots. Use --isolated to keep the profile in memory, or --storage-state auth.json to start from a known login.
5. Images flood the context window
Every screenshot the agent takes is sent back to the model as an image unless you say otherwise. A long QA session with 20 full-page captures can push useful text out of context. --image-responses omit keeps the files on disk but stops sending the image parts to the client. That works well when screenshots are evidence for humans and the agent does not need to look at them.
A config that produces predictable screenshots
For a screenshot-focused setup, put the flags in the MCP client config instead of retyping them. This example works in any client that uses the standard mcpServers JSON (Claude Desktop, Cursor and others):
Then give the agent a prompt that names the file and the mode:
The last sentence matters. Without it, many agents take a screenshot after every step "to check progress", which is slow and expensive.
What a screenshot costs in tokens
Anthropic's vision documentation estimates image cost at roughly width × height / 750 tokens, and large images are scaled down before the model sees them. Other providers use different formulas, but the order of magnitude is similar.
| Capture | Approx. size | Approx. tokens (Claude estimate) |
|---|---|---|
| Viewport, 1280×720, scale css | 1280×720 | ~1,200 |
| Same viewport, scale device on a 2x screen | 2560×1440 before downscaling | Downscaled by the model to its size limit, so a similar token count but a larger upload |
| Accessibility snapshot of a typical page | Text | Varies widely; often less than a screenshot for simple pages |
The practical rule: let the agent read with snapshots and look with screenshots. One screenshot at the end of a task to confirm the visual result is usually enough.
When a hosted screenshot tool fits better
Playwright MCP drives a real local browser. That is what you want when the agent must log in, fill forms and click through a flow. It is more than you need when the job is "capture these 30 URLs" or "compare staging and production". In those cases a local browser adds install steps, headed windows and disk management.
SnapshotFlow exposes an MCP endpoint at https://api.snapshotflow.com/mcp with five tools: screenshot, batch_screenshot, visual_diff, extract_text and check_job. Rendering happens on our side, the image comes back in the tool response together with JSON metadata, and there is no browser to install on the agent's machine. Cloud agents that cannot launch Chromium can still capture pages this way.
| Job | Playwright MCP | SnapshotFlow MCP |
|---|---|---|
| Multi-step flow with login and clicks | Best fit | Only cookies/headers, no step-by-step clicking |
| Capture many public URLs | One page at a time | batch_screenshot, up to 10 URLs per call |
| Before/after comparison | Two screenshots, the model compares | visual_diff returns a diff image and changed-pixel stats |
| Hide cookie banners and ads | Agent has to click them away | block_cookie_banners, block_ads |
| Runs without a local browser | No | Yes |
Many teams run both: Playwright MCP for interactive work and a hosted tool for bulk or scheduled captures. Setup instructions for Claude, Cursor, Copilot and Codex are on the SnapshotFlow MCP page.
FAQ
Can Playwright MCP take screenshots?
Yes. browser_take_screenshot captures the viewport, the full page with fullPage: true, or one element with target. It ships in the core tool set.
Where is the Playwright MCP screenshot folder?
Screenshots without a filename go to the output directory set by --output-dir or PLAYWRIGHT_MCP_OUTPUT_DIR. Screenshots with a filename are saved relative to the workspace root. Set the output directory explicitly if you want a stable location.
Can Playwright MCP record video instead?
Yes, with the DevTools capability. Start the server with --caps=devtools and the agent gets browser_start_video and browser_stop_video. Without a filename, the video is saved into the output directory as video-{timestamp}.webm. The same group adds tracing tools. For a single visual result, a screenshot is still simpler to review and attach.
Why can't the agent click what it sees in the screenshot?
Actions use element refs from browser_snapshot. Coordinate-based tools such as browser_mouse_click_xy exist, but only when you start the server with --caps=vision.
Sources and further reading
- microsoft/playwright-mcp README: tool reference and the full list of CLI options.
- Playwright page.screenshot() reference for the library defaults that differ from the MCP tool.
- Anthropic vision documentation for image token estimates.
- WebMCP explained and AI agent UI verification on this blog.
Give your agent a screenshot tool without a local browser
Connect the SnapshotFlow MCP server next to Playwright MCP and let your agent batch-capture pages, compare before and after, and hide cookie banners in one call. The free tier gives you 300 screenshots, no credit card required.