How to add Playwright MCP to Claude Code

4 min read.
Tags: AIClaude Code

Playwright MCP gives Claude Code a real browser: it can open pages, click, fill forms, read the console, and take screenshots. Adding the Playwright MCP server to Claude Code takes one command.

Quick command

claude mcp add playwright npx @playwright/mcp@latest

The alias is playwright. Claude Code starts the server locally over stdio with npx, so you need Node.js 18 or newer. No account or token is involved.

Verify it works

claude mcp list

You should see:

playwright: npx @playwright/mcp@latest - ✓ Connected

"Connected" only means the MCP server started. The browser launches later, on the first tool call. So test with a real page inside Claude Code:

Use playwright to open https://example.com and tell me the page title.

If Claude answers "Example Domain", everything works. If the tool call fails, read the next section.

Fix "Chromium distribution 'chrome' is not found"

On a machine without Google Chrome, the first tool call fails with this:

Error: Chromium distribution 'chrome' is not found at /opt/google/chrome/chrome
Run "npx playwright install chrome"

By default, Playwright MCP drives Google Chrome, the normal branded browser, rather than the Chromium build that Playwright ships for tests. The server connects without Chrome, but every browser tool fails until it can find it.

You have two ways out. Install Google Chrome normally, or let the error's command do it:

npx playwright install chrome

Or switch to Playwright's own browser with --browser chromium. With that flag, the server asks for a chrome-for-testing build, which you install through the MCP package:

npx @playwright/mcp@latest install-browser chrome-for-testing
claude mcp remove playwright
claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium

The second option works on Linux servers and CI images where you don't want a full Chrome install.

Passing flags: put them after --

Server flags go after a -- separator:

claude mcp add playwright -- npx @playwright/mcp@latest --headless

Without --, the Claude Code CLI tries to read --headless as one of its own options. The Claude Code docs describe the same rule for any stdio server: everything after -- goes to the server untouched.

The flags you will probably reach for:

  • --headless runs the browser without a window. The default is headed. Use headless over SSH, in CI, or when you don't need to watch.
  • --browser chromium|firefox|webkit|msedge picks the browser. Install the matching browser first.
  • --isolated keeps the browser profile in memory, so cookies and logins are gone when the session ends.
  • --caps vision,pdf,devtools turns on extra tool groups that are off by default.
  • --device "iPhone 15" emulates a device.

npx @playwright/mcp@latest --help prints the full list.

Logins stick around between sessions

Without --isolated, Playwright MCP keeps a persistent browser profile per workspace. On Linux it lives in ~/.cache/ms-playwright/mcp-{channel}-{workspace-hash}, and on macOS in ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}.

That's handy when you log in to your app once and Claude stays logged in. It also means any session Claude opens can use those cookies. If you test against production accounts, use --isolated, or delete that folder when you're done.

Ignore .playwright-mcp/

Page snapshots and screenshots land in a .playwright-mcp/ folder in the directory where Claude Code runs. Add it to .gitignore before it ends up in a commit:

echo ".playwright-mcp/" >> .gitignore

Or move the output somewhere else with --output-dir.

Pin it per project

@latest downloads whatever is newest when the server starts. For a team setup, add the server at project scope with a fixed version so everyone runs the same one:

claude mcp add --scope project playwright -- npx @playwright/mcp@0.0.83 --headless

That writes it to .mcp.json in the repo root, which you can commit. At the time of writing, 0.0.83 is the latest release on npm. Check with npm view @playwright/mcp version.

Watch out for look-alike packages

Search results also show @executeautomation/playwright-mcp-server. That is a separate community project with its own tool names and flags. Every command above is for Microsoft's @playwright/mcp. If a guide's flags don't match what you see in --help, check which package it uses.

MCP or the Playwright CLI?

The Playwright MCP README itself suggests that coding agents may do better with Playwright CLI and skills, because CLI calls don't load large tool schemas and accessibility trees into the model's context. MCP fits longer browser sessions where Claude keeps state across many steps, such as clicking through a checkout flow. For "open this page and tell me what's broken", either works.

References

Other MCP setups on this blog: GitHub, Datadog, and Context7.

Final check

Run claude mcp add playwright npx @playwright/mcp@latest, then test with a real page, not only claude mcp list. If the first tool call can't find Chrome, install it, or switch to --browser chromium after installing chrome-for-testing.

Related Posts