Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To install Playwright MCP, use Node.js 20 or newer and add the server command npx @playwright/mcp@latest to an MCP-compatible client. The package is started on demand through npx; Playwright downloads its browser automatically the first time the server is used. This guide shows the generic configuration, client-specific commands, verification task, browser and profile options, HTTP mode, troubleshooting, and when Playwright MCP is a better fit than Playwright CLI.
What you need before installing
- Node.js 20 or newer. The current official getting-started and installation pages require Node.js 20+. The repository README has stated Node.js 18+ at times, so use Node.js 20+ as the conservative requirement unless the package documentation for the version you pin says otherwise.
- An MCP client. Examples include VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, Cline, Goose, Kiro, Codex and Copilot CLI. Each client decides where its MCP configuration is stored.
- Permission to download browsers. The first real request downloads the browser binary automatically, so the initial interaction can take longer and may require network access.
Check your runtime with:
node --version
npm --versionIf the Node version is below 20, install a current Node.js release before adding the server. Do not confuse this package with the Playwright Test runner, the Playwright Library, or @playwright/cli; those are separate tools.
Add the server to an MCP client
Universal configuration
Where your client accepts an MCP server map, add this entry:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}Save the configuration, then use the client’s documented reload, reconnect, or restart action. Configuration file paths and reload controls differ between clients, but the npx command and package argument are the shared core.
#1 Best Overall
Claude Code
Run this in a terminal:
claude mcp add playwright npx @playwright/mcp@latestAfter the command completes, start a new Claude Code session or use its MCP status command to confirm that the server is available.
VS Code
VS Code can add the server from its command line:
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'You can also add the same command and arguments through VS Code’s MCP interface if your edition exposes it. Restart or reload the workspace when prompted.
Cursor
- Open Cursor Settings.
- Open MCP.
- Choose Add new MCP Server.
- Select the command-type server and enter
npx @playwright/mcp@latest. - Save it and reconnect the agent if Cursor does not discover it immediately.
Claude Desktop and other clients
Open the client’s MCP installation guide and create a server entry equivalent to the universal JSON above. Claude Desktop, Windsurf, Cline, Goose, Kiro, Codex and Copilot CLI may use different settings screens or configuration files. Do not assume a path documented for one client works in another.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Verify that Playwright MCP works
Do not rely only on a green “connected” label. Give the assistant a small browser task:
- Ask it to navigate to
https://demo.playwright.dev/todomvc. - Ask it to add several todo items.
- Ask it to report the resulting list.
A functioning server exposes the page’s accessibility snapshot and element references, allowing the agent to locate controls and interact with them. The browser normally opens in headed mode, so you should see a window. The first run may pause while the browser is downloaded.
Playwright MCP primarily reasons over structured accessibility data rather than requiring a vision model. Its tools also provide screenshots when visual confirmation is useful.
Rank #2
Control the browser, session and state
Headed versus headless
Headed mode is the default and is useful while debugging. To run without a visible window, add --headless:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"]
}
}
}Select a browser
The documented browser values are chrome, firefox, webkit and msedge. For example:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--browser=firefox"]
}
}
}Use the browser that matches the compatibility question you are investigating. A browser-specific issue should be reproduced in that browser rather than inferred from Chromium behavior.
Persistent and isolated profiles
Persistent profile mode is the default, preserving cookies and login state between uses. This is convenient for authenticated development sites, but it can also make a test depend on stale state. Add --isolated for a fresh in-memory session:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--isolated"]
}
}
}State held only in an isolated session disappears when the browser closes. To provide known cookies or local-storage values at startup, use --storage-state with a state file:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--storage-state=/absolute/path/state.json"
]
}
}
}Keep state files out of source control: they can contain active authentication data.
Rank #3
Use a JSON configuration file
For repeatable advanced settings, create a configuration file and pass it with:
npx @playwright/mcp@latest --config path/to/config.jsonThe configuration format covers browser options, context options, network rules, timeouts and other server behavior. Keep the file path accessible to the account that launches the MCP client, and use an absolute path when the client starts from an unexpected working directory.
Run Playwright MCP over HTTP
Some IDE workers and remote environments cannot launch a local stdio process conveniently. The official guide documents a standalone HTTP server:
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11npx @playwright/mcp@latest --port 8931Point the MCP client at:
http://localhost:8931/mcpThis mode is intended for environments such as headed browsers on systems without a normal display or IDE worker processes. HTTP sessions use a five-second heartbeat timeout by default. Set PLAYWRIGHT_MCP_PING_TIMEOUT_MS to change that value, or disable the heartbeat according to the server’s documented environment-variable behavior. If a remote client is involved, bind and firewall the service according to your environment rather than exposing a local automation endpoint publicly.
MCP or Playwright CLI?
| Choose | Best fit | Interaction model |
|---|---|---|
| Playwright MCP | An MCP-capable assistant that needs a browser tool | Persistent state and iterative reasoning over page structure, with accessibility snapshots, element references and screenshots |
| Playwright CLI | A coding agent workflow optimized for compact command output | Token-efficient, skill-based CLI commands rather than an MCP server connection |
Install @playwright/mcp when your client expects an MCP server. Install or invoke the separate CLI when your agent workflow specifically calls for CLI commands and skills. Installing one does not configure the other.
Troubleshoot common installation problems
“Node.js version is unsupported”
Cause: Your runtime is older than the current documented prerequisite. Fix: upgrade to Node.js 20 or newer, open a new terminal, verify with node --version, and reconnect the MCP client.
Rank #4
The client shows no server or tools
Cause: Invalid JSON, a client-specific configuration location, or a client that has not reloaded its settings. Fix: validate commas and quotes, confirm the server name is playwright, use the client’s own MCP settings screen or guide, then restart or reload it.
Free tools Windows power users keep installed
One-click scans. No signup required.
npx cannot download the package
Cause: No network access, a proxy restriction, registry authentication, or a blocked npm process. Fix: run npx @playwright/mcp@latest directly in a terminal to expose the underlying error, configure the required proxy or registry, and retry. Pinning a version can improve reproducibility once you have selected a version deliberately, but the official examples use the moving @latest tag.
The browser does not appear
Cause: You enabled --headless, are running in a display-less worker, or the browser download failed. Fix: remove --headless on a desktop, or keep headless mode in a server environment; then run a simple TodoMVC task and inspect the terminal output for download or display errors.
Login state is missing
Cause: You used --isolated, selected a different profile, or supplied an incorrect storage-state path. Fix: use persistent mode for a retained profile, or provide a valid absolute --storage-state file. Avoid sharing authentication state with untrusted agents.
HTTP mode disconnects
Cause: The heartbeat expires after inactivity or a proxy closes the connection. Fix: keep the server reachable at http://localhost:8931/mcp, adjust PLAYWRIGHT_MCP_PING_TIMEOUT_MS when appropriate, and verify that the IDE worker and server use the same host and port.
Or skip the browser setup
If your goal is a dependable image or PDF of a URL rather than interactive browser control, ScreenshotNeo provides a single-call website screenshot API and an MCP server for AI agents. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result.
For a direct image request, see the ScreenshotNeo API documentation:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://demo.playwright.dev/todomvc -o shot.webpThe same endpoint works from Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://demo.playwright.dev/todomvc"}, timeout=90)
open("shot.webp", "wb").write(r.content)Or Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://demo.playwright.dev/todomvc' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo also supports full-page and element captures, device and viewport settings, dark mode, retina scale, PDFs, custom CSS and JavaScript, clicks, waits, request blocking, cookies, headers, geolocation, caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage data and an OpenAPI specification. Its MCP tools are take_screenshot, get_page_info and capture_pdf. Every feature is available on every plan: 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000 shots. Sign up for the free plan.
Frequently Asked Questions
Does installing Playwright MCP install Playwright Test?
No. @playwright/mcp is an MCP server package. Playwright Test, the Playwright Library and Playwright CLI are separate packages and workflows.
Can I use Playwright MCP without a graphical desktop?
Yes. Add --headless for a hidden browser, or run the documented HTTP server with --port 8931 when an IDE worker or remote environment needs an HTTP MCP endpoint.
Where does Playwright MCP store its configuration?
There is no universal path. VS Code, Cursor, Claude Code, Claude Desktop and other clients expose different configuration interfaces; use the selected client’s MCP documentation.
Why does the first request take longer than later requests?
The first use can download the browser automatically. Subsequent starts can reuse the downloaded browser, subject to the client and environment.
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.
Recommended Free Tools
