ScreenshotNeo
Sign in Get a free key

BlogAI agents

Playwright Test MCP: Complete Setup and Usage Guide

Install Playwright MCP, connect it to Cursor or VS Code, run browsers headlessly, manage profiles, and deploy it safely in production.

By the ScreenshotNeo team1 October 20268 min read

Playwright Test MCP is Microsoft’s Model Context Protocol server for browser automation. It lets MCP-compatible clients such as Cursor, VS Code, Windsurf, Claude Code and Claude Desktop drive Playwright browsers through structured accessibility snapshots. The model can navigate pages, inspect elements, click, type, fill forms and manage tabs without relying on a vision model.

The shortest path is to run the official npm package from your MCP client:

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

Use Node.js 20 or newer for the current getting-started guidance. The package metadata declares Node.js 18 or newer. For reproducible builds, replace @latest with a version you have tested.

What Playwright Test MCP does

The server exposes browser actions as MCP tools. An agent first receives an accessibility snapshot, then uses references from that snapshot in subsequent calls. This gives the model a structured representation of links, buttons, fields and other page elements.

  • Navigate to URLs and inspect page structure.
  • Click links and controls.
  • Type into fields and submit forms.
  • Fill form controls using their accessible names.
  • Handle multiple tabs and browser pages.
  • Run browser-oriented test and investigation workflows.

Optional capability groups add network, storage, PDF, vision, devtools and testing tools. Start with core browser automation, then enable only the groups your workflow needs.

Install Playwright MCP

1. Check Node.js

node --version
npm --version

Use Node.js 20 or newer for the current guide. If your environment is pinned to Node.js 18, verify the exact package version and client compatibility before deployment.

2. Add the MCP server to your client

Create or edit the MCP configuration used by your client:

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

The same command pattern works in MCP clients that accept a command and argument list. Client-specific locations and reload steps differ, so use the client’s MCP settings interface when available.

3. Connect and verify

Restart or reload the MCP client, then ask the assistant to open the Playwright TodoMVC demo and add a few items. A successful run confirms that the client can start the server and that browser actions are available.

How the accessibility-tree interaction works

  1. The agent requests a page snapshot.
  2. Playwright returns structured elements and accessible names.
  3. The model chooses an element reference from that structure.
  4. The MCP server performs an action such as click, type or fill.
  5. The agent requests another snapshot and continues.

This approach is often more deterministic than interpreting pixels when a page exposes correct semantic roles and names. Poorly labelled controls, canvas-heavy interfaces and content rendered only after custom JavaScript can still require additional handling or the optional vision capability.

Browser modes and channels

The getting-started flow uses headed mode by default. Use headless mode for CI, containers and unattended jobs:

npx @playwright/mcp@latest --headless

Playwright MCP documents browser selection for Chromium-based Chrome, Firefox, WebKit and Microsoft Edge channels. Choose a channel that matches the browser behavior you need to reproduce.

Choice Use it when Trade-off
Headed Debugging locally or watching an agent run Requires a display and is less convenient in CI
Headless CI, Docker and unattended automation Visual debugging requires traces, logs or a headed reproduction
Chromium/Chrome Most Chromium-compatible production sites Does not represent Firefox or WebKit differences
Firefox Cross-browser checks or Firefox-specific behavior Browser-specific rendering and feature differences remain
WebKit Safari-like coverage Some sites behave differently from Chromium
Edge channel Microsoft Edge compatibility Requires the matching channel to be available

Persistent profiles, isolated sessions and extensions

Use a persistent profile when the agent must retain cookies, local storage or an existing login session. Use an isolated context when every run should start clean and sessions must not share state.

  • Persistent profile: keeps browser state between runs. Protect the profile directory because it may contain authenticated sessions.
  • Isolated session: starts fresh, which is useful for repeatable tests and tenant separation.
  • Extension mode: can connect to existing browser tabs where the client and browser setup support it.

Do not put production credentials in a profile that an unrestricted agent can access. Use a dedicated account with the minimum permissions required by the workflow.

Configuration options

A JSON configuration file can define browser and context options, network rules and timeouts. Keep configuration in version control when it contains no secrets, and inject secrets through the deployment environment.

Useful configuration decisions include:

  • Browser and channel selection.
  • Headed or headless operation.
  • Persistent profile directory or isolated contexts.
  • Navigation and action timeouts.
  • Allowed hosts and network restrictions.
  • Optional capability groups such as network, storage, PDF, vision, devtools and testing.

Pin the package version after validating a release:

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

The official package metadata identifies @playwright/mcp version 0.0.82, authored by Microsoft Corporation and licensed under Apache-2.0. Release numbers change, so check the official package and releases before pinning a new version.

Run Playwright MCP over HTTP

The server can run as a standalone HTTP service on port 8931 and expose /mcp for clients that connect over HTTP. This is useful when the browser runs on a dedicated host or container.

npx @playwright/mcp@latest --headless --port 8931

Configure the client to connect to the service using its MCP HTTP transport settings. Put authentication, TLS termination and network access controls in front of a remotely reachable service.

Run it in Docker

The project documents an official Docker image. The Docker implementation currently supports headless Chromium.

docker pull mcr.microsoft.com/playwright/mcp

docker run --rm \
  --init \
  --ipc=host \
  mcr.microsoft.com/playwright/mcp

For CI, mount only the directories the workflow needs, pass credentials through a secret manager, and keep the container network limited to required hosts. If you need Firefox, WebKit or a headed browser, use a deployment that provides those channels instead of assuming the Docker image covers them.

Security and production boundaries

The project README states: Playwright MCP is not a security boundary. Treat the MCP client, browser, network, filesystem and secrets as separate security concerns.

  • Restrict which hosts the browser may visit.
  • Do not expose an HTTP endpoint broadly without authentication and network controls.
  • Use isolated profiles for untrusted or multi-tenant work.
  • Keep credentials out of prompts and page content.
  • Review whether a page can inject instructions that influence the model.
  • Limit filesystem mounts and browser permissions in containers.
  • Log tool calls and failures without recording secret values.

The configuration reference includes allowed hosts and secret replacement, but secret handling is described as a convenience rather than a security feature. Threat-model the complete deployment before allowing an agent to access private systems.

Common errors and fixes

Error or symptom Likely cause Fix
npx cannot start the server Node.js is missing or too old Install a supported Node.js release and verify with node --version.
The client shows no Playwright tools Invalid MCP JSON or the client was not reloaded Validate the configuration, restart the client and inspect its MCP logs.
Browser fails in CI Headed mode has no display Start with --headless or provide a virtual display.
Actions cannot find an element The element is not exposed in the accessibility tree, has changed, or is inside a different page Request a fresh snapshot, use the accessible name, wait for navigation and verify the active tab.
Login disappears between runs An isolated session is being created each time Use a protected persistent profile or perform login during each run.
HTTP clients cannot connect Wrong port/path, firewall rule or missing proxy configuration Confirm port 8931, the /mcp path and network access from the MCP client.
Docker browser crashes Container shared-memory limits are too small Use the documented container flags such as --ipc=host and review container resources.
Site content tries to redirect the agent Page content is being treated as instructions Apply host restrictions, isolate credentials and require explicit approval for sensitive actions.

Performance and reliability practices

  • Use headless mode and reuse a warm browser process for repeated CI jobs.
  • Set explicit navigation and action timeouts instead of relying on indefinite waits.
  • Wait for a meaningful selector or page state before acting on dynamic content.
  • Keep snapshots focused by navigating to the relevant page and closing unused tabs.
  • Use isolated contexts in parallel jobs to prevent cookie and local-storage collisions.
  • Capture diagnostics such as console output, failed URLs and tool-call timing.
  • Pin a tested MCP version and update it deliberately.
  • Retry transient browser startup or navigation failures with a bounded retry count.

Browser automation remains sensitive to site changes, third-party outages, bot checks and authentication expiry. Treat a successful tool call as evidence that an action ran, then verify the resulting page state before continuing.

When you need screenshots instead of browser interaction

Playwright MCP is designed for an agent that must inspect and operate a page. If your output is a clean image or PDF, a screenshot API can remove browser setup and make the capture repeatable.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP or PDF. Before capture it accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be turned off.

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

See the ScreenshotNeo API documentation for the full parameter list. It supports full-page and element captures, device presets, custom viewports, retina scale, dark mode, PDF options, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous jobs, webhooks, bulk capture and usage reporting.

Bot checks, blank pages, timeouts, failed loads and cache hits cost nothing. Every response reports the result through X-Page-Verdict and X-Billed headers. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.

The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.

FAQ

Is Playwright MCP the same as Playwright Test?

No. Playwright MCP is an MCP server that exposes browser automation to an LLM. Playwright Test is Playwright’s testing framework. They can be used in related workflows but serve different interfaces.

Does the model need a vision model?

The documented interaction model uses structured accessibility snapshots and does not require a vision model for core actions. Vision is an optional capability for workflows that need it.

Can I use a saved login?

Yes. Use a persistent profile and protect its directory. Use isolated sessions when state must be discarded between runs.

Should I use @latest in production?

Pin a version you have tested. The latest release and package behavior can change over time.

Is the HTTP server safe to expose publicly?

No default MCP configuration makes it a security boundary. Add authentication, TLS and network restrictions, and limit browser hosts and credentials.

When is a screenshot API a better fit?

Use one when the required result is a screenshot or PDF rather than interactive browser control. It avoids managing browser processes and can standardize cleanup, waits and billing behavior.

Keep reading