How to Set Up Playwright MCP

Use Node.js 20 or newer, an MCP-compatible client, and the official @playwright/mcp@latest package. Add this server definition to your client, reload it, then ask the assistant to open https://demo.playwright.dev/todomvc and create a few tasks:

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

Playwright MCP gives an MCP client browser automation through structured accessibility snapshots. The browser is downloaded automatically on first use. The exact configuration location differs by client. See the official getting-started guide and installation documentation.

What you need before starting

Node.js 20 or newer. This is the prerequisite listed by the current Playwright MCP getting-started guide.
An MCP client. Examples include VS Code, Cursor, Windsurf, Claude Code and Claude Desktop.
Permission to download and launch a browser. The first MCP use downloads the required browser automatically.
A terminal if you plan to use a client CLI or a generic JSON configuration.

Check the client’s current instructions as part of setup. Client configuration paths and reload steps can change independently of the Playwright package.

Install Playwright MCP with the standard configuration

1. Confirm Node.js

node --version

Use Node.js 20 or later. If your shell reports an older version, install a current Node.js release before continuing. A separate Microsoft sample page mentions Node.js 18, but that applies to a different context; follow the current Playwright MCP guide for this server.

2. Add the server to your MCP client

Use the JSON definition below wherever your client accepts MCP servers:

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

npx resolves and runs the package. You do not need a separate global installation for the standard setup.

3. Reload or restart the client

Restart the client, reload its MCP settings, or use its documented refresh action. Look for a connected playwright server and its browser tools.

4. Run a smoke test

Ask the assistant to navigate to https://demo.playwright.dev/todomvc, add three todo items, and report the resulting list. This checks the complete connection and interaction loop: MCP transport, browser launch, navigation, accessibility snapshot and an action.

Client-specific setup

VS Code

The official guide shows a CLI route:

code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

If your VS Code version uses a settings UI instead, add the same command and arguments as a command-type MCP server, then reload the window.

Claude Code

claude mcp add playwright npx @playwright/mcp@latest

Start a new Claude Code session or reload MCP connections, then run the TodoMVC smoke test.

Cursor

Open Cursor Settings.
Open the MCP section.
Add a command-type server named playwright.
Set the command to npx and the argument to @playwright/mcp@latest.
Reload the MCP connection and run the smoke test.

Claude Desktop, Windsurf and other clients

Use the generic JSON definition. Put it in the client’s documented MCP configuration file or UI, preserving the command and argument exactly. The file path, environment-variable syntax and reload behavior are client-specific.

Choose a browser and runtime mode

Keep the default first. Add options only when your environment requires them. The configuration reference documents the available flags.

Need	Configuration direction	When to use it
No display or CI runner	Add `--headless`	Servers, containers and automated jobs without a desktop.
Specific browser engine	Choose Chrome, Firefox, WebKit or Microsoft Edge	Testing browser-specific behavior.
Repeatable advanced settings	Pass `--config path/to/config.json`	Centralize browser and context options.
Existing login, SSO, 2FA or extensions	Connect to an existing Chrome/Edge channel, CDP endpoint, Playwright server endpoint or browser extension	Reuse a session that a newly launched browser cannot access.
Remote or shared deployment	Run the standalone HTTP server and configure the client URL	Separate the MCP server process from the client.

Headless mode

The default configuration runs a headed browser. Add the flag in the server arguments when no display is available:

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

Browser selection

Use the browser option documented by your installed version when you need Chrome, Firefox, WebKit or Edge. Keep the selected engine aligned with the behavior you are investigating; changing engines can change rendering, permissions and available channels.

Configuration files

For advanced browser and context settings, pass a JSON file:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--config", "path/to/config.json"]
    }
  }
}

Use the option names and schema from the official configuration reference.

Use an existing authenticated browser

A fresh server-launched browser is isolated. That is useful for reproducibility, but it will not contain your existing SSO session, 2FA state or installed extensions. When a task depends on those, Playwright documents several connection paths:

a Chrome or Edge channel;
a Chrome DevTools Protocol (CDP) endpoint;
a Playwright server endpoint; or
the Playwright browser extension, which can reuse existing tabs and logged-in state.

Start with the isolated browser. Switch to an existing-browser connection only when the task requires its session state. Review the browser connection documentation for the exact flags and extension flow.

Run Playwright MCP as an HTTP server

Local command mode is the simplest setup. For a separately managed process, the setup guide also documents starting Playwright MCP on a port and configuring the client with an HTTP URL. This is useful when the client and browser host are different processes or machines.

Account for the documented heartbeat timeout when configuring a remote client. Keep the server reachable from the client, protect the endpoint with your network controls, and verify the client URL before debugging browser actions. The HTTP transport is an optional deployment pattern; it is not required for ordinary local use.

How the interaction loop works

The MCP client starts the Playwright MCP process with npx.
The server launches or connects to a browser.
The assistant requests a page navigation or action.
Playwright returns a structured accessibility snapshot and action results.
The assistant chooses the next action from that structured page representation.

Use accessible names, roles and page structure in your instructions. The TodoMVC smoke test is valuable because it exercises navigation, form input, button activation and state reporting without requiring a private account.

Common errors and fixes

Error or symptom	Likely cause	Fix
`node: command not found`	Node.js is not installed or is not on `PATH`.	Install Node.js 20 or newer, open a new terminal and rerun `node --version`.
Node version rejected	The runtime is older than the current MCP prerequisite.	Upgrade to Node.js 20 or newer. Do not substitute a version from an unrelated sample.
Server never appears in the client	Invalid JSON, wrong settings location or no client reload.	Validate the JSON, confirm the server name is `playwright`, then restart or reload MCP connections.
`npx` cannot resolve the package	Network, registry or shell restrictions.	Run `npx @playwright/mcp@latest` in the same environment, check registry access and inspect the client’s stderr/logs.
Browser download fails	First-use download is blocked or incomplete.	Allow the download in the runtime environment, retry, and check disk space and network policy.
Browser starts then closes	Headed mode is running without a display, or the process lacks required runtime permissions.	Add `--headless` in a display-less environment and inspect the client/server log.
Actions cannot reach a logged-in page	The server launched a clean profile without your cookies or extensions.	Use a documented existing-browser connection, CDP endpoint or browser extension.
Remote client disconnects	Incorrect HTTP URL, blocked port or heartbeat timeout.	Verify the URL and network route, keep the server running, and apply the heartbeat settings from the setup guide.
Assistant cannot identify a control	The page exposes an unexpected or incomplete accessibility tree.	Ask for a fresh page snapshot, use the visible role/name, wait for the page to finish loading, or target a simpler state.

Reliability, performance and cost considerations

Startup time: the first run includes package resolution and browser download. Warm runs avoid that initial download.
Isolation: a newly launched browser profile makes tasks reproducible, while reused profiles improve access to authenticated systems but carry session-state dependencies.
Headless deployment: use it for servers and CI where no display exists; retain headed mode when visually inspecting behavior locally.
Browser choice: pick the engine that matches the behavior under investigation. Cross-browser differences are expected.
Remote transport: HTTP adds a network path and heartbeat configuration. Keep the client and server close enough for stable connectivity.
Package freshness: @latest, supported flags and client integrations can change. Recheck the official docs after upgrades.
Cost: the research sources describe software setup and automatic browser download, but provide no usage pricing or benchmark. Plan infrastructure and model costs separately for your environment.

When you only need a clean screenshot

Playwright MCP is suited to an AI agent that must navigate and interact. If your job is simply to turn a URL into a screenshot or PDF, ScreenshotNeo removes the browser setup and exposes a single HTTP endpoint. Its clean-shot pipeline accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and each response reports the result in X-Page-Verdict and X-Billed headers.

Or skip the browser setup

Call the ScreenshotNeo API directly. See the ScreenshotNeo API documentation for the options and response details.

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

Cookie banners, popups and chat widgets are removed before the shot.
Bot checks, blank pages and failed loads are never billed.
An MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.
Every feature is available on every plan: full-page and element capture, device presets, retina scale, PDF controls, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, geolocation, caching, signed links, async jobs, bulk capture and a usage API.
There are 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and start with 1,000 screenshots a month without a card.

FAQ

Does Playwright MCP require a separate Playwright project?

No. The standard MCP configuration runs the published server with npx. A separate application project is only needed when you are building your own automation around Playwright.

Can I use Playwright MCP without a graphical desktop?

Yes. Add --headless to the server arguments for a display-less environment.

No. The standard server launches an isolated browser. Use a documented channel, CDP or extension connection when the task needs existing authenticated state.

Which client should I choose?

Use the MCP client already used by your team. The server definition is the same; only the client’s configuration location and reload process differ.

Should I use Playwright MCP for every screenshot job?

Use it when an agent must browse and interact. For direct URL-to-image or PDF capture, ScreenshotNeo can handle the capture through one request.