Skip to content

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.json file 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 npx available in the PATH — the final config starts the server with npx @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:

MCP error -32000: Connection closed
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:
where mcp-server-playwright   # (or whatever command you have configured)
npm view @playwright/mcp version
If the first one finds nothing and the second one does return a version, it's this incident — follow the same steps below.

Steps to follow:

  1. Remove the broken entry:

    claude mcp remove playwright
    
  2. Add it again with the official package (@playwright/mcp):

    claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated
    

    (the --isolated flag is to avoid Incident 4 — see below).

  3. Check:

    claude mcp list
    

Final configuration (correct):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
    }
  }
}
Expected result: 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...
Even if one of the two is correct, the scope conflict means the browser_* tools never get registered in the session.

Steps to follow:

  1. Confirm which scopes it's defined in:

    claude mcp get playwright
    
  2. Keep only one definition. Remove the one from the scope you're not going to use (the usual thing is to remove the project one and keep the local one, so as not to force the config on the whole team through the repo):

    claude mcp remove playwright -s project
    
  3. 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"]
    }
  }
}
(without the --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
It happens when two Claude Code sessions (or an old session that got stuck) try to control the same Chrome profile at the same time. Without --isolated, all sessions share a single browser profile — the second one that tries to use it runs into a lock.

Steps to follow:

  1. If you have another Claude Code session open using Playwright, close it (or wait for it to finish) — that releases the lock right away.
  2. To keep this from happening again, add --isolated to the server's args:

    claude mcp remove playwright
    claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated
    
  3. Restart VS Code (see Incident 3) and try again.

Final configuration (correct):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
    }
  }
}
With --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
When you use @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:

  1. 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 its package.json):

    npx @playwright/mcp@latest install-browser chrome-for-testing
    
  2. 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.


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:

  1. Restart VS Code completely.
  2. Check with claude mcp list → it should appear only once as ✓ Connected.
  3. Start a new session and confirm that the browser_* tools are available before running lippia-neo-run-manual-testing or 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, run npx @playwright/mcp@latest install-browser chrome-for-testing again.