How to Configure Playwright MCP to Capture a Webpage Screenshot After Network Idle

Direct answer: Playwright MCP does not have a server setting that automatically waits for networkidle before every screenshot. In one browser session, navigate to the page, explicitly call page.waitForLoadState('networkidle') through browser_run_code_unsafe, and then call browser_take_screenshot.

1. Configure the Playwright MCP server

Use Node.js 20 or newer and an MCP client. Add the Playwright server entry to the MCP configuration file used by your client. Where that file lives depends on the client; the official Playwright MCP getting-started guide provides examples for VS Code, Cursor, Claude Code, Claude Desktop, and others.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Restart or reload the MCP client as needed so it starts the server and discovers its tools. The standard configuration exposes the navigation, screenshot, wait, and code execution tools needed below. You do not need an optional capability group for this basic workflow.

2. Navigate, wait, and capture

Call browser_navigate with the target page URL.
Call browser_run_code_unsafe in the same browser session with the code below.
After the wait completes, call browser_take_screenshot with the desired capture scope and output options.

async (page) => {
  await page.waitForLoadState('networkidle');
  return 'Network idle reached';
}

The function receives the current Playwright page. The wait applies to that page; navigating in another session or capturing before this tool call finishes defeats the sequence. browser_run_code_unsafe executes arbitrary JavaScript in the MCP server process and is documented as equivalent to remote code execution. Use it only with a Playwright MCP server and client you trust. See the Playwright API reference and MCP documentation.

3. Choose what to capture

browser_take_screenshot captures the current viewport by default. Choose one scope:

Viewport: omit both target and fullPage for the visible area.
Element: set target to an element reference or selector.
Full page: set fullPage: true to capture the scrollable page.

Do not combine target and fullPage. The tool supports PNG, JPEG, and WebP. Set filename to control the saved name; relative filenames resolve against the workspace root. If you omit it, the tool returns an automatically named image in the output directory and inline in the response unless image responses are omitted. Set scale to css (the default) or device for device-pixel-ratio sizing.

// Example tool arguments for a full-page PNG:
{
  "fullPage": true,
  "filename": "page.png",
  "type": "png",
  "scale": "css"
}

Use the MCP client’s tool schema for the exact argument envelope it expects; the options above describe the screenshot tool’s relevant capture settings.

4. Decide whether network idle is the right readiness signal

Playwright defines networkidle as no network connections for at least 500 milliseconds. That is a network-activity heuristic, not proof that the content you care about has finished rendering. Playwright discourages using this state as a testing readiness signal and recommends web assertions instead.

For a page with polling, analytics, streaming, or other persistent requests, the page may never reach network idle. A later client-side update can also change the page after the wait. If a specific page element or response indicates readiness more directly, wait for that condition instead. For example, with trusted code execution enabled:

async (page) => {
  await page.goto('https://example.com');
  await page.locator('[data-page-ready="true"]').waitFor({ state: 'visible' });
  return 'Page-specific ready element is visible';
}

Replace the example URL and selector with the page and a real readiness marker. If you already navigated using browser_navigate, omit page.goto and wait on the current page. A fixed delay can be useful for a known animation or delayed visual transition, but it is less reliable than waiting for a meaningful page condition.

5. Configuration options and tool behavior

The server configuration can set browser and context options, network rules, timeouts, and output settings. The documented configuration sources are a config file, environment variables, and command-line arguments, with later sources taking precedence. Consult the official MCP configuration reference for supported names and syntax for your installed version.

There is no documented configuration switch that makes browser_take_screenshot automatically wait for networkidle. Keep readiness as an explicit step, or use a page-specific condition in code. The browser_wait_for tool can wait for text to appear or disappear, or for a delay capped at 30 seconds; it does not accept a network load-state parameter. General action settling by the MCP server is not the same as explicitly waiting for Playwright’s network-idle state.

6. Troubleshooting

Symptom	Likely cause	Fix
The MCP client does not show Playwright tools	The server entry is in the wrong client config, the client has not reloaded, or `npx`/Node.js is unavailable.	Check the client-specific setup instructions, confirm Node.js 20 or newer and `npx` are available to the client process, then reload the MCP server and inspect its startup error.
The screenshot happens before the wait	The capture was issued before `browser_run_code_unsafe` completed or in a different browser session.	Await the code tool result, then call the screenshot tool in the same session.
The network-idle wait times out	Ongoing requests, polling, or long-lived connections prevent 500 ms of network quiet.	Wait for a specific visible element or application signal. If network idle is essential, inspect which requests remain active and whether the application can reach a quiet period.
The capture is blank or missing recently loaded content	The page’s visual update occurs after network quiet, or a lazy element has not entered the viewport.	Wait for the relevant element or content condition. Scroll the element into view where appropriate, then capture after it is visible.
Element capture cannot find its target	The selector is wrong, the element is not yet present, or it is inside a frame or shadow root not addressed by that selector.	Confirm the selector against the live page and wait for the target to appear before capture; use a suitable element reference or page-aware locator.
Full-page capture conflicts with target	The two options represent incompatible capture scopes.	Choose either a target element or `fullPage: true`.
The image is unexpectedly large or blurry	`scale` changes pixel dimensions; device scale can produce more pixels than CSS scale.	Choose `css` for CSS-pixel sizing or `device` for device-pixel-ratio sizing, then select the required image type.

7. Performance, reliability, and cost

The explicit wait adds at least the time needed for the page to reach a quiet 500 ms interval, plus navigation, rendering, and screenshot work. Pages with continuous traffic can turn that wait into a timeout. A page-specific readiness condition usually avoids waiting for unrelated requests and better matches the content the screenshot needs to show.

For repeatable captures, use the same viewport/context settings, wait for a stable application signal, and capture in the same session. Treat a successful network-idle wait as evidence only that the network was quiet under Playwright’s definition; it does not guarantee that an image, animation, font, or later UI update is visually complete. Playwright MCP is open-source software; this workflow has no per-screenshot API price specified by the cited setup documentation. Your compute and browser hosting costs depend on where you run the MCP server.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. For a one-call capture, use the API with your key. See the ScreenshotNeo API documentation for request options.

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

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

9. FAQ

Does MCP configuration alone make screenshots wait for network idle?

No. Configure the server to expose the tools, then explicitly wait on the page before calling the screenshot tool.

Does network idle mean the page is fully rendered?

No. It describes a period without network connections. Use a page-specific readiness condition when visual completion depends on application behavior.

Can I capture a single element and the entire page in one screenshot?

No. The screenshot tool does not allow target and fullPage together.