Playwright MCP setup guide
This guide solves the 5 connection incidents that came up repeatedly
when setting up the Playwright MCP server for the QA skills
(lippia-neo-run-manual-testing, lippia-neo-reproduce-bug, lippia-neo-run-exploratory-session). It's designed so that, if you run into
any of these errors, you know exactly what to check and which command to run —
without having to investigate all over again.
Prerequisites
This guide uses the Claude Code CLI commands (
claude mcp ...) as a reference, because they're the ones documented in this level of detail today. The.mcp.jsonfile diagnosed in the incidents below is the same for Codex and Copilot — what changes is the command to list/add/remove the MCP server, which depends on each assistant's CLI or extension. If you use Codex or Copilot, look up the equivalent command in that tool's documentation; the logic of each incident (what's wrong and why) is the same.
- Claude Code CLI installed and working — all the commands in this
guide (
claude mcp ...) are run from there. - Node.js with
npxavailable in the PATH — the final config starts the server withnpx @playwright/mcp@latest, so npx has to be able to resolve and download that package. - Playwright browsers installed — if this is the first time you're using
Playwright on this machine, install the browsers before setting up the
MCP (this installs Chromium, Firefox, and WebKit):
npx playwright install**Important: ** If you're using VSCode, the repository that Claude Code is pointed at or looking at must be the test repository. Otherwise, it may not find the MCP when setting up the bootstrap.
How to check the MCP status (always the first step)
claude mcp list
Look for the playwright line. It can give you 3 results:
✓ Connected→ the server is correctly registered (but see Incident 3 — "Connected" doesn't always mean the tools are already available).✘ Failed to connect→ see Incident 1.- It appears twice (in different scopes) → see Incident 2.
If claude mcp list shows ✓ Connected but the browser_* tools
don't show up when you look for them (ToolSearch in Claude Code, or they simply
can't be invoked), go straight to Incident 3.
Incident 1 — "Failed to connect" due to an incorrect package name
Initial configuration (broken):
{
"mcpServers": {
"playwright": {
"command": "mcp-server-playwright",
"args": ["--browser", "chromium"]
}
}
}
What happens:
claude mcp list
playwright: mcp-server-playwright --browser chromium - ✘ Failed to connect
mcp-server-playwright is not a real npm package — nothing exists under that
name. That's why the process never starts.
Variant of the same symptom: instead of (or before) running
claude mcp list, you may directly see this error in the chat when trying to use a Playwright tool:It's the same Incident 1 seen from the MCP client side: the server's stdio process never managed to start (nonexistent command), so the connection closes as soon as it opens. Confirm it by running:MCP error -32000: Connection closedIf the first one finds nothing and the second one does return a version, it's this incident — follow the same steps below.where mcp-server-playwright # (or whatever command you have configured) npm view @playwright/mcp version
Steps to follow:
-
Remove the broken entry:
claude mcp remove playwright -
Add it again with the official package (
@playwright/mcp):claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated(the
--isolatedflag is to avoid Incident 4 — see below). -
Check:
claude mcp list
Final configuration (correct):
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
}
}
}
playwright: npx @playwright/mcp@latest --browser chromium --isolated - ✓ Connected.
Incident 2 — The server is duplicated in two different scopes
Initial configuration (broken): playwright defined at the same time in the
project scope (the repo's .mcp.json) and in the local scope (personal config),
each one with a different command (for example, one with the broken package from
Incident 1 and another with the correct package).
What happens:
[Warning] Server "playwright" is defined in multiple scopes with different
endpoints: project (mcp-server-playwright --browser chromium),
local (npx @playwright/mcp@latest). OAuth tokens are stored per endpoint...
browser_* tools never get registered in the session.
Steps to follow:
-
Confirm which scopes it's defined in:
claude mcp get playwright -
Keep only one definition. Remove the one from the scope you're not going to use (the usual thing is to remove the
projectone and keep thelocalone, so as not to force the config on the whole team through the repo):claude mcp remove playwright -s project -
Restart VS Code completely (close and reopen the window, not just the chat) so the session starts clean.
Final configuration: a single playwright entry, in a single scope,
with the correct command from Incident 1. Check with claude mcp list that
it appears only once and without warnings.
Incident 3 — The tools don't show up even though the server is "Connected"
Initial configuration: correct .mcp.json, claude mcp list showing
✓ Connected, but when you look for the tools (browser_navigate, browser_click,
etc.) none of them show up.
What happens: the VS Code/Claude Code session was opened before the Playwright server became available (for example, you configured or fixed it with the session already open). The tools of a new MCP aren't hot-loaded into a session that was already running.
Steps to follow: 1. Close VS Code entirely (not just the chat tab/window). 2. Open it again. 3. Start a new Claude Code session and try again.
Final configuration: nothing changes in the config file — the fix is purely "restart the session after touching the MCP config". General rule: every time you add, remove, or modify an MCP server, restart VS Code before using it again.
Incident 4 — "Browser is already in use"
Initial configuration (broken):
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--browser", "chromium"]
}
}
}
--isolated flag)
What happens:
Error: Browser is already in use for
C:\Users\<user>\AppData\Local\ms-playwright-mcp\mcp-chrome-<hash>,
use --isolated to run multiple instances of the same browser
--isolated, all sessions share a single browser profile —
the second one that tries to use it runs into a lock.
Steps to follow:
- If you have another Claude Code session open using Playwright, close it (or wait for it to finish) — that releases the lock right away.
-
To keep this from happening again, add
--isolatedto the server's args:claude mcp remove playwright claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated -
Restart VS Code (see Incident 3) and try again.
Final configuration (correct):
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
}
}
}
--isolated, each session starts its own isolated browser profile,
and several can run in parallel without stepping on each other.
Incident 5 — "Browser ... is not installed" due to an out-of-sync version of @playwright/mcp@latest
Initial configuration (broken): any config that uses @playwright/mcp@latest (the
one recommended in this guide), on a machine where Playwright browsers were already installed
from a previous run.
What happens:
Error: Browser "chrome-for-testing" is not installed; expected executable at
C:\Users\<user>\AppData\Local\ms-playwright\chromium-1237\chrome-win64\chrome.exe
@latest, each run can bring a different version of the
@playwright/mcp package, and each version bundles a different Playwright revision (and
therefore expects a different Chrome-for-Testing revision). If the machine only has
an old revision installed (for example 1228) and that run's npx downloaded a newer
version that asks for 1237, the browser never opens — any skill that depends on
browser_navigate is blocked before it reaches the app.
Steps to follow:
-
Install the revision the current MCP expects, using the MCP's own command (not
playwright install chromium, which may bring a different revision if the project has another Playwright version declared in itspackage.json):npx @playwright/mcp@latest install-browser chrome-for-testing -
If the error persists, check which revision the error message asks for and confirm that that folder exists in
%LOCALAPPDATA%\ms-playwright\(Windows) or~/.cache/ms-playwright(Linux/Mac).
How to avoid it in the future: pin a fixed version of @playwright/mcp instead of
@latest (e.g. @playwright/mcp@0.x.y) in .mcp.json / qa-stack.yaml, so the
expected revision doesn't change on its own between runs. If you prefer to stay on @latest, run
npx @playwright/mcp@latest install-browser chrome-for-testing every time you update or
reinstall dependencies — not just the first time.
Recommended final configuration (solves incidents 1 to 4 at once)
claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated
Defined only once, in a single scope, with the official
@playwright/mcp package and the --isolated flag. After configuring it this way:
- Restart VS Code completely.
- Check with
claude mcp list→ it should appear only once as✓ Connected. - Start a new session and confirm that the
browser_*tools are available before runninglippia-neo-run-manual-testingor any other skill that depends on the browser.
Incident 5 isn't prevented by this configuration: it depends on the version of
@playwright/mcp@latest. Every time you update or reinstall dependencies, runnpx @playwright/mcp@latest install-browser chrome-for-testingagain.