Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

To set up Playwright MCP, use Node.js 20 or newer, add the @playwright/mcp@latest server to an MCP-compatible client, then ask your assistant to open a test page and interact with it. The general server configuration is small; the exact place to enter it depends on whether you use Cursor, VS Code, Claude Code, Claude Desktop, Windsurf, or another client. Playwright’s current getting-started guide lists Node.js 20+ and an MCP client as prerequisites.

What Playwright MCP does

Playwright MCP is a browser-automation server that lets an MCP-compatible AI client operate a browser. Its interactions use structured accessibility snapshots, which give the assistant a representation of page content and controls to work with. It is useful for tasks such as navigating pages, entering form data, and checking a web workflow; it is not a guarantee that every site or login flow will work without configuration.

The setup below launches the server locally through npx. The Playwright installation guide says the browser downloads automatically on first use, so the initial browser launch may take longer than later ones. See Playwright MCP installation for current installation details.

Prerequisites

  • Node.js 20 or newer. This is the requirement in the current Playwright MCP getting-started guide. A separate Microsoft Learn page for Power Platform samples gives a different minimum for its own context; use the Playwright MCP guide for this setup, and check the relevant client or sample documentation if you are following another environment.
  • An MCP-compatible client. The guide gives VS Code, Cursor, Windsurf, Claude Code, and Claude Desktop as examples. The method and configuration location vary by client.
  • Network access on first use. The server is invoked with npx, and the browser download occurs automatically on first use.

Add Playwright MCP to your client

Generic MCP configuration

For a client that accepts a standard server configuration, add this JSON entry where that client expects MCP servers:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Save the configuration and use the client’s reload, restart, or server-management flow to make it take effect. The client’s own documentation determines the file path and reload procedure; there is no single config path shared by all MCP clients. The latest tag follows the package’s current release, so behavior and flags can change as the package evolves.

VS Code

Playwright’s getting-started guide documents a VS Code CLI route using code --add-mcp. Follow the current guide’s exact command and any prompts for your installed VS Code version rather than copying a config path intended for a different client. After adding the server, confirm it appears in the client’s MCP server list and is enabled.

Cursor

  1. Open Cursor Settings → MCP.
  2. Add a command-type MCP server.
  3. Set the command to npx and its arguments to @playwright/mcp@latest, following the fields exposed by your Cursor version.
  4. Save the entry and verify that Cursor reports the server as connected or available.

Claude Code

The documented command is:

claude mcp add playwright npx @playwright/mcp@latest

Run it in a terminal where the claude command is available. Then check the MCP server status using Claude Code’s current server-management interface or command help.

Other clients

Use the generic configuration if the client accepts it, but consult that client’s current MCP instructions for the actual settings screen, configuration file, and reload steps. A server entry can be correct while the client still fails to start it because it reads a different config location or requires a different transport.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Verify the connection with a small browser task

  1. Ask the assistant to navigate to https://demo.playwright.dev/todomvc.
  2. Ask it to add a few todo items, then inspect whether they appear on the page.
  3. Confirm that the client opens or controls the browser and returns a meaningful result.

This smoke test checks the connection and basic page interaction loop. It does not establish that a site with authentication, bot defenses, unusual controls, or special browser requirements will work with the default launch settings.

Choose optional browser settings when needed

Headless or visible browser

The documented default runs headed, meaning the browser is visible. Add --headless when no visible window is wanted or the machine has no display. Use the default headed mode when you need to watch the browser during debugging. See Playwright MCP configuration options for the current flags.

Choose a browser

The configuration options documentation lists Chrome, Firefox, WebKit, and Microsoft Edge as supported values and shows a Firefox example. Select a different browser only when your test or target behavior calls for it; browser-specific behavior can differ. Check the current option spelling and supported channels in the documentation before changing the launch arguments.

Pass advanced configuration

For browser and context options, the configuration reference documents passing a JSON configuration file with --config path/to/config.json. Use a real path readable by the process launching the MCP server. If the server fails after adding a config file, temporarily remove that option to check whether the basic launch works, then validate the JSON and option names against the current reference.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use an existing authenticated browser

When a task needs a logged-in session, SSO, 2FA, or an installed browser extension, a clean server-launched browser may not have the state the task requires. Playwright documents connecting through a Chrome or Edge channel, a CDP endpoint, a Playwright server endpoint, or a browser extension. The extension can reuse existing tabs and logged-in browser state. This is an optional, more involved route; begin with the standard launched browser unless session reuse is necessary. Details are in Connecting Playwright MCP to browsers.

Run a standalone HTTP server

The setup guide also documents starting the server on a port and configuring a client to use an HTTP transport URL, with a heartbeat timeout note. This is a deployment alternative for clients or environments that need a separately reachable server, not a prerequisite for ordinary local setup. Follow the current guide for the port, URL, and timeout details rather than assuming the local command configuration applies unchanged.

Troubleshoot common setup failures

The MCP client does not show Playwright

  • Check that the entry is in the configuration location used by that specific client.
  • Confirm the server is enabled and reload or restart the client after saving changes.
  • For a command-based entry, confirm the executable is npx and the argument is @playwright/mcp@latest, without adding JSON punctuation to a UI field.

The server will not start

  • Check that Node.js is version 20 or newer, as specified by the current Playwright MCP getting-started guide.
  • Ensure the machine can access the package and browser download on first use.
  • If you added optional flags or a JSON config, remove them temporarily and try the standard entry. Reintroduce options one at a time and check their current names in the official configuration reference.

The browser does not appear

The default is headed, but a visible window may not be available in a headless server or remote environment. Add --headless for a no-display environment. If you expect a visible browser, verify that the process has access to a display and that the client launched the server you configured.

The server connects but a task fails on a particular site

First separate connection success from site-specific behavior: retry the TodoMVC smoke test, then consider whether the target depends on an authenticated profile, a browser channel, or another setting. For SSO or 2FA workflows, consult the documented existing-browser connection approaches. Do not treat a successful demo test as proof that every website can be automated.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Remote or HTTP setup does not connect

Check that the client’s configured URL matches the server’s actual transport and port, and review the setup guide’s heartbeat timeout note. A local command configuration and a separately hosted HTTP server are different connection patterns; do not mix their settings.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Performance, reliability, and operational choices

The simplest local configuration is usually the easiest to debug: one client launches one MCP server, which in turn launches a browser. The first use may include the automatic browser download. Headless mode changes display behavior, not the underlying requirement for a compatible browser installation. A standalone HTTP deployment introduces endpoint and heartbeat configuration, while connecting to an existing browser trades a fresh session for access to that browser’s state.

For routine development, start with the standard config and demo task before layering on browser choice, profiles, or remote transport. This isolates configuration errors and makes it clearer whether a failure belongs to the MCP client, server launch, browser environment, or target website.

Or skip the browser setup

If your goal is to capture a web page as an image or PDF rather than have an AI agent interact with it, ScreenshotNeo is a screenshot API and MCP server. A single request can return a screenshot; it is not a substitute for Playwright MCP when you need browser interaction. Its cleanup accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers indicate the page verdict and billing status. It also offers MCP tools for AI agents: take_screenshot, get_page_info, and capture_pdf.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Example cURL request for a WebP capture:

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

Replace YOUR_API_KEY with your key and change the target URL as needed. See the ScreenshotNeo API documentation for request options and output formats.

ScreenshotNeo includes 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.

Frequently asked questions

Does Playwright MCP require a paid plan?

The setup described here is a software package and MCP client configuration; the cited setup instructions do not establish a paid plan requirement.

Can Playwright MCP use my logged-in browser?

Yes. Playwright documents extension and browser-connection approaches for reusing existing browser state; use them when a fresh launched browser cannot satisfy the session requirement.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Does the TodoMVC test prove the setup works on every website?

No. It confirms basic connection and interaction on a demo page only. Sites can impose additional browser, authentication, or interaction requirements.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.