How to Fix the Playwright MCP Server Startup Error

Start by identifying the stage that failed. A Playwright MCP startup error can mean that your MCP client could not spawn the process, the process started but MCP initialization failed, or the MCP server connected and the first browser operation failed. These require different fixes.

Copy the complete error, then record your MCP client, operating system, Node.js version, and whether Playwright tools appear before the failure. The current Playwright getting-started documentation uses Node.js 20 or newer; a repository README has shown Node.js 18 or newer, so verify the requirement for the exact package version you run.

1. Classify the failure before changing settings

What you see	Likely stage	First place to look
`command not found`, spawn error, or immediate exit	Process spawn	Node/npm PATH, command, permissions
`connection closed`, server disconnected, or initialization timeout	MCP connection or initialization	Client configuration, package download, MCP logs
Tools appear, but navigation or browser creation fails	Browser launch	Browser download, display, sandbox, browser option

Copy the exact error text, including nested causes.
Run node --version and note the executable used by your shell.
Check whether the MCP client shows a connected Playwright server and tools such as browser navigation.
Only then change browser, headless, or transport options.

The Playwright MCP server provides browser automation through the Model Context Protocol, allowing an LLM to interact with pages through structured accessibility snapshots. See the official getting-started guide.

2. Verify Node.js and the executable visible to your MCP client

Use Node.js 20 or newer as the current documentation baseline:

node --version
npm --version
which node
which npx

A GUI-launched client can inherit a different PATH from your terminal. Compare the paths reported by your shell with the environment used by the client. If npx is missing for the client, configure an absolute executable path or fix the client’s environment according to its documentation.

Do not diagnose a browser problem until npx can start the package. The official installation documentation says the browser is downloaded automatically on first use, so a browser download failure may occur after MCP itself has connected.

3. Check the command and arguments

The standard server stanza is:

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

Use the configuration file and schema required by your client. A valid stanza in the wrong file or scope has no effect. Reload or restart the client after editing it.

Claude Code

claude mcp add playwright npx @playwright/mcp@latest

VS Code

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

These are documented examples, not universal file paths. Confirm the command and scope against the version of your MCP client. Pinning a package version can improve reproducibility, but choose a version compatible with your client and Node runtime.

4. Separate MCP connection errors from browser launch errors

If the client cannot connect or initialize

Inspect MCP logs for command not found, package-fetch failures, permission errors, malformed JSON, and invalid argument errors.
Run the same npx @playwright/mcp@latest command in a terminal to expose npm or network diagnostics.
Check that the client is reading the configuration file and scope you edited.
Restart the client after every configuration change.

If tools appear but the first browser operation fails

Allow the first-use browser download to finish, or inspect the download error and filesystem permissions.
Check whether the environment has a display. Playwright MCP runs headed by default.
Only select Chrome, Firefox, WebKit, or Microsoft Edge when the error points to browser selection or that browser’s installation.

5. Fix headed and headless display problems

For CI, containers, SSH sessions, and IDE workers without a display, add --headless:

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

Headless mode is usually the simplest choice when no visible browser is required. If you need headed operation from a display-less worker, run a separate HTTP server and point the client at it:

npx @playwright/mcp@latest --port 8931

Configure the client to use http://localhost:8931/mcp. The server process must remain running, and the client URL, port, and route must match exactly. If the client runs in a container and the server runs elsewhere, verify network reachability. The configuration guide documents --host 0.0.0.0 for binding all interfaces; restrict network exposure to the intended network.

Choice	Use it when	Operational requirement
Headless	No visible browser or display is available	Pass `--headless` to the server
Standalone HTTP	A separate worker has a display or owns the browser process	Keep the server alive and make the MCP URL reachable
Default headed stdio	The client process has a working display	Start the package directly with `npx`

6. Reproduce with a minimal first interaction

After restarting the MCP client, verify that the server is shown as connected before opening your own site. Use the simple page from the getting-started guide:

https://demo.playwright.dev/todomvc

If this page works, the MCP process and browser are probably healthy; investigate target-site authentication, certificates, proxies, or navigation behavior separately.

7. Common errors and fixes

Error pattern	Cause to check	Fix
`npx: command not found`	The MCP client cannot see your Node installation	Install or expose Node.js, compare PATH values, or configure an absolute command path.
Server exits immediately	Malformed config or unsupported argument	Reduce to `npx @playwright/mcp@latest`, validate JSON, then add options one at a time.
Package fetch or network error	npm registry, proxy, certificate, or offline environment	Run the same command in a terminal, fix registry or proxy access, and retry.
Connection closed during initialization	Wrong client scope, process crash, or incompatible runtime	Inspect MCP logs, confirm Node 20+, and restart after correcting the stanza.
Browser failed to launch	First-use browser download, missing libraries, display, or sandbox policy	Read the browser-specific error, complete the download, use headless mode where appropriate, and follow the environment’s browser dependency guidance.
Works in terminal but not in IDE	Different PATH, working directory, permissions, or environment variables	Compare executable paths and environment, then configure the IDE’s MCP server explicitly.
HTTP client cannot reach server	Wrong port or route, stopped process, or container networking	Keep the server running, use `http://localhost:8931/mcp`, and verify reachability from the client host.

8. Reliability and performance considerations

Use a pinned package version in repeatable CI deployments after confirming compatibility.
Keep browser downloads in a prepared environment when startup latency matters.
Prefer one long-lived HTTP server for multiple clients only when its lifecycle and network boundary are controlled.
Use headless mode in workers without a display; headed mode adds a display dependency.
Capture logs from both the MCP client and server. The stage of failure is more useful than a generic “startup error” label.

9. Or skip the browser setup

If your goal is a reliable screenshot rather than interactive browser control, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF, so there is no Playwright process, browser download, or display to configure.

cURL (see the ScreenshotNeo API docs):

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

Python:

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 accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info, and capture_pdf 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. Create a free ScreenshotNeo account.

FAQ

Is Node.js 18 enough?

The current official getting-started documentation says Node.js 20 or newer. A repository README has shown 18 or newer, so check the requirement for the package version you use and prefer Node 20+ for a current setup.

Should I change the browser first?

No. Change browser selection only when the error identifies a browser or its launch. First confirm the MCP process and initialization succeed.

Why does the first browser action fail after the server connects?

Playwright MCP downloads its browser automatically on first use. That download or the local display and dependency checks can fail after MCP tools are already available.

When should I use HTTP transport?

Use the documented standalone HTTP mode when a separate process should own a headed browser or when an IDE worker cannot provide a display. Ensure the process stays running and the client can reach its MCP route.

What information should I include when asking for help?

Include the exact error, MCP client and version, operating system, Node.js version, server command and arguments, and whether tools appeared before the failure.

Checklist

Node.js 20 or newer is available to the MCP client.
The client uses the correct configuration file and scope.
The command is npx with @playwright/mcp@latest or a compatible pinned version.
MCP logs show whether the failure is spawn, initialization, or browser launch.
Headless mode is enabled when no display exists, or the HTTP server route is reachable.
The client was restarted and a simple page was tested before the target site.

For the authoritative option names and transport details, consult the Playwright MCP configuration guide and installation guide.