Install the Playwright MCP server by running it through an MCP client with Node.js 20 or newer. Add the shared server entry npx @playwright/mcp@latest to your client, reconnect, and verify it by asking the assistant to open https://demo.playwright.dev/todomvc and add todo items. The browser downloads automatically the first time the server is used.
This guide covers generic MCP configuration, Claude Code, VS Code, Cursor, Claude Desktop, HTTP mode, browser and profile settings, verification, troubleshooting, and the difference between Playwright MCP and Playwright CLI.
What you are installing
Playwright MCP is an MCP server that lets an AI assistant operate a real Playwright browser. It is not the Playwright Test runner, the Playwright Library, or the separate playwright-cli package. The server exposes browser actions and returns structured accessibility snapshots with element references, so an agent can reason about page structure and interact with controls. Screenshots are also available for visual checks.
The package is launched on demand with the moving npm tag @playwright/mcp@latest. The official installation material does not establish a fixed package version or release date, so pin a version only after checking the package information you intend to support.
#1 Best Overall
Prerequisites
Node.js 20 or newer
The official getting-started and installation guidance requires Node.js 20 or newer. The project repository README has also stated Node.js 18 or newer, but that conflicts with the current installation guidance. Use Node.js 20 or newer as the conservative baseline; if you must run Node.js 18, verify compatibility for the exact package version first.
An MCP-compatible client
You need a client that can start an MCP server, such as VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, Cline, Goose, Kiro, Codex, or Copilot CLI. Each client decides where its configuration is stored and how a connection is reloaded. The command and arguments below are the portable part.
Node and npm checks
Confirm the runtime before changing your client configuration:
node --version
npm --versionThe first command should report a major version of 20 or higher. npx is included with standard npm installations and is what starts the server.
Recommended Free Tools
Install Playwright MCP in a generic MCP client
- Open your client’s MCP-server configuration screen or file. Do not assume another client’s file path applies to yours.
- Add this server definition:
{"mcpServers":{"playwright":{"command":"npx","args":["@playwright/mcp@latest"]}}}- Save the configuration and use the client’s documented reload, reconnect, or restart action.
- Start a small browser task rather than relying only on a connected indicator. Ask the assistant to navigate to
https://demo.playwright.dev/todomvcand add a few todo items.
On first use, Playwright downloads the browser automatically. The initial launch can therefore take longer and may require an internet connection and permission to write to the normal Playwright browser-cache location.
Client-specific setup commands
Claude Code
Claude Code provides a command-line shortcut:
claude mcp add playwright npx @playwright/mcp@latestRestart or reload the Claude Code session if the server does not appear immediately. The name playwright is a label; you can choose another name, but keeping it consistent makes later troubleshooting easier.
VS Code
With the VS Code command-line interface, add the server as follows:
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'Open the MCP view in VS Code and confirm that the server is enabled. If your shell treats single-quoted JSON differently, use the quoting convention required by your operating system.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Rank #2
Cursor
- Open Cursor Settings.
- Open MCP.
- Choose Add new MCP Server.
- Use a command-type server and enter
npx @playwright/mcp@latest, or enternpxas the command and@playwright/mcp@latestas its argument, depending on the form shown by your Cursor build. - Save it and enable the server.
Claude Desktop
Use Claude Desktop’s MCP installation flow and paste the standard configuration entry. Claude Desktop’s configuration location and restart behavior are client-specific, so follow the labels in the version you have installed rather than copying a path from another operating system.
Windsurf, Cline, Goose, Kiro, Codex and other clients
The same server command works in other MCP clients named by the Playwright guide. Find the client’s MCP documentation, create a server named playwright, set the command to npx, and set the argument to @playwright/mcp@latest. If the client accepts a single command string, use npx @playwright/mcp@latest.
Verify that the server works
Use a state-changing but harmless demo
Send this instruction to the connected assistant:
Navigate to https://demo.playwright.dev/todomvc and add three todo items: Buy milk, Send invoice, and Backup photos.A successful run should open the page, obtain an accessibility snapshot, identify controls through element references, enter the items, and report the resulting state. This tests startup, browser availability, navigation, page parsing, and interaction in one short task.
What a failure tells you
- If the client cannot start the process, inspect Node.js, npm, and the exact command in the client configuration.
- If the process starts but the browser is missing, allow the automatic first-use browser download and check filesystem or network restrictions.
- If navigation works but controls cannot be found, ask the agent to inspect the current accessibility snapshot before attempting another action.
Configure browser mode, engine and session state
The default server behavior is headed mode with a persistent profile. You can change these settings in the server arguments.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Need | Argument or setting | Effect |
|---|---|---|
| Hide the browser window | --headless |
Runs without a visible browser window. |
| Select a browser | --browser=firefox |
Uses Firefox. Documented values are chrome, firefox, webkit, and msedge. |
| Fresh session each run | --isolated |
Uses an in-memory isolated context; state is lost when the browser closes. |
| Load existing login state | --storage-state path/to/state.json |
Starts with cookies and other saved storage from the supplied state file. |
| Advanced, repeatable settings | --config path/to/config.json |
Loads JSON covering browser options, context options, network rules, timeouts and other settings. |
Headed versus headless
Headed mode is useful while installing because you can see navigation, consent dialogs and authentication prompts. Add --headless for background jobs or machines without a desktop. A headless launch does not remove the need to solve login, network or certificate problems; it only hides the window.
Persistent versus isolated profiles
The default persistent profile preserves cookies and login state, which is convenient for an assistant working across several turns. Use --isolated when reproducibility and clean state matter more than convenience. For a controlled authenticated run, create a storage-state file through your normal Playwright workflow and pass it with --storage-state. Treat that file as a credential because it can contain session cookies.
Use a configuration file for complex environments
When you need several browser, context, timeout or network rules, keep them in JSON and start the server with:
npx @playwright/mcp@latest --config path/to/config.jsonKeep the configuration file readable only by the account that needs it when it references local paths or authenticated state.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
Run Playwright MCP as an HTTP server
Some IDE workers and remote environments cannot conveniently launch a local stdio process with a visible browser. The official guide documents a standalone HTTP mode:
npx @playwright/mcp@latest --port 8931Point the MCP client at:
http://localhost:8931/mcpThis mode is useful when the browser must run in a separate process or host. The documented HTTP session heartbeat timeout is five seconds. Set PLAYWRIGHT_MCP_PING_TIMEOUT_MS to change that timeout, or disable it according to the server’s documented environment-variable behavior. If a remote client is involved, protect the endpoint with your network controls; do not expose an unauthenticated browser-control service to the public internet.
MCP or Playwright CLI?
Installing the right package matters. Playwright MCP is designed for an MCP client that maintains a browser session and reasons iteratively over page structure. Playwright CLI is a separate package and command positioned for token-efficient, skill-based coding-agent workflows.
| Choose | Best fit | Interaction model |
|---|---|---|
| Playwright MCP | Your AI client supports MCP and benefits from persistent browser state. | Server tools return structured page information and support iterative actions. |
| Playwright CLI | Your coding agent is built around command execution and reusable skills. | Token-efficient CLI commands rather than an MCP server connection. |
Do not replace @playwright/mcp with @playwright/cli, playwright, or @playwright/test when following this setup.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsTroubleshoot common installation and runtime errors
“npx” or “node” is not recognized
Cause: Node.js is absent or its installation directory is not on PATH.
Fix: Install Node.js 20 or newer, open a new terminal, and rerun node --version and npm --version. In managed environments, ask the administrator to expose the runtime to the IDE process as well as your interactive shell.
The client says the server exited immediately
Cause: malformed JSON, an incorrect command/argument split, a blocked npm registry, or a runtime version below the supported baseline.
Fix: Test npx @playwright/mcp@latest in a terminal, validate the client’s JSON, and ensure npx is the command while @playwright/mcp@latest is an argument when the client has separate fields. Check the client log for the first error rather than repeatedly reconnecting.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #4
The first request hangs while downloading a browser
Cause: the browser is being downloaded on first use, or a proxy/firewall is blocking the download.
Fix: wait for the initial download, verify outbound access to the package and browser hosts allowed by your organization, and confirm the process can write to its Playwright cache directory. A later launch should not repeat the initial download unless the cache was removed or the browser version changed.
The browser opens but the assistant cannot click anything
Cause: the page may still be loading, the target may be inside a different state than expected, or the requested text may not exist in the current accessibility tree.
Fix: ask the assistant to inspect the latest accessibility snapshot, identify the element reference it sees, and then act on that reference. Avoid assuming a reference from an earlier page state remains valid after navigation or a major DOM update.
Login disappears between tasks
Cause: the server was started with --isolated, or a persistent profile was replaced.
Fix: remove --isolated when you intentionally need persistence, or load a known storage-state file. Keep separate profiles for personal and automated accounts.
HTTP clients disconnect after a few seconds
Cause: the HTTP heartbeat timeout is five seconds by default, and a proxy or worker may delay ping responses.
Fix: keep the HTTP process reachable, check intermediary idle timeouts, and adjust PLAYWRIGHT_MCP_PING_TIMEOUT_MS when the documented server behavior permits it.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallHeadless mode fails on a server
Cause: a headed browser was requested on a machine without a display, or the browser sandbox is restricted by the container.
Fix: add --headless for display-less hosts, grant the process the required browser permissions, and review the host’s container or sandbox policy. Use headed mode locally to diagnose the page before moving the same configuration to a worker.
Operational guidance for reliable agent runs
- Start with a small task. The TodoMVC check isolates installation problems before you involve a production site.
- Keep state intentional. Persistent profiles improve continuity; isolated contexts improve repeatability and reduce accidental data reuse.
- Use accessibility-first prompts. Ask the agent to inspect the current snapshot and then act on the available reference instead of relying on guessed coordinates.
- Separate credentials. Storage-state files and persistent profiles can contain live sessions. Store them outside shared repositories and limit filesystem access.
- Choose browser mode by environment. Headed mode helps diagnose visual and authentication issues; headless mode is generally easier for background workers.
- Expect first-run overhead. Browser installation and profile creation happen before the first useful action, so provision them during setup rather than inside a strict request deadline.
Or skip the browser setup
If your goal is a clean image or PDF of a URL rather than interactive browser control, ScreenshotNeo provides a one-request screenshot API and an MCP server for AI agents. It accepts consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and lets you turn each cleanup step off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and each response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers.
Use the API documentation at https://screenshotneo.com/docs/ for the full option set, including full-page lazy-image loading, CSS-selector element capture, dark mode, 12 device presets or custom viewports, retina scale, PDF paper size and margins, custom CSS and JavaScript, clicks before capture, wait conditions, request blocking, headers, cookies, user agents, Authorization, timezone, geolocation, transparent backgrounds, resizing, configurable cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, usage data and OpenAPI.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo has an MCP server with take_screenshot, get_page_info and capture_pdf tools, so Claude, Cursor and other MCP clients can request captures without you managing a Playwright browser profile. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to get an API key.
Frequently Asked Questions
Does installing Playwright MCP install Playwright Test too?
No. The MCP server is the separate @playwright/mcp package launched with npx; install Playwright Test separately only if you need test-runner features.
Can I use a different npm tag instead of @latest?
You can choose a specific package version when you have verified its compatibility, but the official setup examples use the moving @playwright/mcp@latest tag and do not establish a fixed current version.
Which browser should I choose for cross-browser checks?
The documented selector accepts chrome, firefox, webkit and msedge. Pick the engine that matches the behavior you are investigating, then keep it consistent for repeatable runs.
Is an MCP connection indicator enough to prove the setup works?
No. A short TodoMVC task verifies that the server can launch a browser, navigate, expose an accessibility snapshot and complete an interaction.
Quick Recap
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.
