How to Capture a Webpage Screenshot with an MCP Server in Docker

Direct answer: run a Playwright MCP server in Docker, connect an MCP-compatible client to it, navigate to the page, then call browser_take_screenshot. Use a regular screenshot for the current viewport, a target to capture an element, or fullPage: true for the scrollable page. Full-page capture and element targeting cannot be combined.

This guide uses the documented Docker MCP Catalog stdio setup and separately describes Microsoft’s repository HTTP example. Keep each image, command, and transport paired with its own documented setup. Then use the ScreenshotNeo option below if you want an image or PDF without running a browser container.

1. Choose how the MCP server should run

An MCP client can start the server as a child process over stdio, or connect to a long-lived server over HTTP. Choose based on how you want to manage the process:

Choice	When it fits	Documented setup
Client-spawned stdio	The MCP client should start and stop the server as needed.	Docker MCP Catalog uses `docker run -i --rm mcp/playwright`.
Long-lived HTTP	You want to start the server separately and point an MCP client at its URL.	The Microsoft repository example publishes port `8931` and connects to `http://localhost:8931/mcp`.

The examples use different image names and flags because they come from different documented setups. Do not combine the catalog image with the repository’s flags without checking that image’s own instructions. The repository notes that its Docker implementation supports headless Chromium.

Option A: Docker MCP Catalog with stdio

Configure your MCP client to launch the catalog’s image as a stdio server. The command shown by the catalog is:

docker run -i --rm mcp/playwright

Put that command in the client’s MCP server configuration using the syntax and configuration location required by that client. Configuration varies by client, so consult its MCP setup instructions. The Playwright MCP guide lists clients including VS Code, Cursor, Windsurf, and Claude Desktop.

This command is a server launch command, not a screenshot command. Once the client connects, ask it to navigate to a URL and take a screenshot, or use the tools directly as described below.

Option B: Microsoft repository Docker example with HTTP

For a separately started HTTP server, the repository documents this Docker example:

docker run -i --rm --init --pull=always \
  -p 8931:8931 \
  --entrypoint /bin/sh \
  mcr.microsoft.com/playwright/mcp \
  -c "node cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0"

Configure the MCP client to connect to:

http://localhost:8931/mcp

The server listens on all interfaces inside the container, while Docker publishes the port on the host. Keep the server process running while the client uses it. This repository example uses mcr.microsoft.com/playwright/mcp; it is distinct from the catalog’s mcp/playwright stdio example.

2. Navigate to the page

After the client connects, navigate the browser to the page you want to capture. The Docker MCP Catalog lists browser_navigate as a tool. In an MCP client, you can ask it to open a URL, or invoke the tool with the URL according to the tool schema exposed by the server.

For reliable captures, use the exact page URL and wait until the page has rendered the content you need. If the page requires authentication, account for that in the browser session and apply the client’s trust and access controls. A screenshot records what the browser rendered; it does not establish that the page content is correct or complete.

3. Capture a viewport, element, or full page

Call browser_take_screenshot after navigation. The tool’s scope is controlled by its parameters:

Desired result	Screenshot setting	Notes
Visible viewport	Omit `target` and `fullPage`.	Captures the currently visible browser viewport.
One element	Set `target` to the element to capture.	Useful for a chart, card, or other specific region.
Full scrollable page	Set `fullPage: true`.	Cannot be combined with an element target.

For example, ask the MCP client: “Navigate to https://example.com and save a full-page screenshot as page.png.” Or request a screenshot of a specific element using the tool’s target parameter. The catalog documents navigation and screenshot tools; exact argument-entry syntax depends on your MCP client.

Choose format, filename, and scale

Format: PNG, JPEG, or WebP.
Filename: set filename to choose a name. Relative filenames resolve against the workspace root.
Default output: if you omit filename, the tool uses a timestamped default in its output directory. Omitting it also returns the image inline to the model unless image responses are suppressed.
Scale: scale: "css" uses CSS pixels and is the default; scale: "device" uses device-pixel resolution.

A typical request might specify type: "png", filename: "page.png", and scale: "css". Use the exact parameter casing and schema exposed by the server. See the [official screenshot tool reference](https://playwright.dev/mcp/tools/screenshots) for the supported screenshot parameters.

4. Find the file or image result

If you set a filename, the screenshot is saved using that name; a relative path is resolved from the workspace root. Without a filename, the server chooses a timestamped name in its output directory. The tool can also return the image inline to the model when no filename is supplied, unless image responses are suppressed.

If a client reports an image but you cannot find a file, check whether you omitted filename and received an inline result instead. If you need a predictable artifact for later use, specify a filename and confirm which workspace the MCP client exposes to the server.

5. Use snapshots for page structure

Screenshots are useful for checking visual layout, charts, canvas content, and documenting a visual bug. For page text, structure, and locating controls for interaction, use the accessibility snapshot. Playwright MCP works with the accessibility tree and provides references that the client can pass to interaction tools. A screenshot is visual evidence; it does not replace those element references. See the [Playwright MCP guide](https://playwright.dev/docs/getting-started-mcp).

Or skip the browser setup

If your task is to get a webpage image or PDF rather than operate a browser through an agent, [ScreenshotNeo](https://screenshotneo.com) provides a screenshot API and MCP server. Its API accepts one GET request with a URL and returns a PNG, JPEG, WebP, or PDF. See the [API documentation](https://screenshotneo.com/docs/).

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}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. [Create a free account](https://screenshotneo.com/account/sign-up/).

Security and trust boundaries

Docker helps package and run the server, but it is not a complete security boundary. Microsoft’s repository explicitly says Playwright MCP is not a security boundary. The server can browse pages requested by its client, so use client-level permissions and trust controls appropriate to your environment.

The Playwright MCP guide warns that browser_run_code_unsafe executes arbitrary JavaScript in the server process and is equivalent to remote code execution. Only enable it for trusted MCP clients. Do not enable unsafe code execution just to take screenshots; navigation and screenshot tools cover the workflow in this guide.

Performance, reliability, and cost

Performance: no benchmark is available in the cited setup documentation. Capture time depends on the page and its resources. Full-page images can contain much more content than viewport captures; CSS scale uses CSS pixels, while device scale uses device pixels.
Reliability: keep the server process and client connection alive during navigation and capture. For HTTP, make sure the published port and configured MCP URL match. For stdio, ensure the client can run Docker and read the workspace where output is saved.
Output size: choose PNG, JPEG, or WebP based on downstream needs. Confirm the generated filename and location before automating later steps around the result.
Cost: the cited setup guides do not state a price for running the server. Account for the Docker environment and compute you provide; do not infer a service price from the documentation.

Troubleshooting

Symptom	Likely cause	What to do
The MCP client cannot start the server.	Docker is unavailable to the client, or the command/configuration does not match the chosen setup.	Confirm Docker is installed and callable from the client’s environment. For catalog stdio, use the catalog’s `mcp/playwright` command. For repository HTTP, use the repository image and flags as documented.
The client connects but cannot reach the HTTP endpoint.	The container is stopped, port `8931` is not published, or the client URL is wrong.	Keep the container running, publish `-p 8931:8931`, and configure `http://localhost:8931/mcp` for the documented repository example.
Screenshot call fails after navigation.	The page may not have rendered or navigation may have failed.	Check the browser state and page URL, then navigate again and capture after the page is ready. For structure and interaction, inspect the accessibility snapshot.
Full-page and element capture do not work together.	The options are mutually exclusive.	Remove `target` for a full-page capture, or omit `fullPage: true` to capture the target element.
The image is too small or too large.	The selected pixel scale does not match the desired output.	Use `scale: "css"` for CSS-pixel output or `scale: "device"` for device-pixel resolution.
No named screenshot appears in the workspace.	No filename was supplied, so the tool used a timestamped default and may have returned the image inline.	Set `filename`, then check the MCP client’s workspace root and output directory.
The page is blank or incomplete in the image.	The requested page may not have loaded its content when capture began.	Verify the destination and page state before capture. A screenshot reflects the browser’s rendered state at that moment.

Frequently asked questions

Can I capture a full-page screenshot and a specific element at once?

No. The screenshot tool does not combine fullPage: true with an element target. Choose one scope per capture.

Does the Docker setup use a headed browser?

The Microsoft repository documents its Docker implementation as supporting headless Chromium.

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

Use the accessibility snapshot to inspect structure and locate controls for interaction. Use a screenshot when visual appearance is what you need to inspect.

Which MCP client configuration should I copy?

Use the configuration instructions for your specific client. The Playwright MCP guide names VS Code, Cursor, Windsurf, Claude Desktop, and other clients, but configuration syntax and location vary.