← All guides

MCPSetup

Playwright MCP with Claude Code: Setup and How to Use It

By Neo Zino - builder of ClockedCode·Updated September 3, 2026·10 min read

Connect Playwright MCP to Claude Code with one claude mcp add command, confirm it works, then run five browser prompts mapped to its real tool names.

Made with DispatchSEO

Run claude mcp add playwright npx @playwright/mcp@latest and Claude Code can open a real browser, click through your app, and read back exactly what's on the page - no screenshots, no you narrating what's broken. That one line is the easy part, and it's also the whole install: no transport flag, no OAuth tab, no key to paste in. What page 1 for this topic skips is what happens after - confirming the connection works, which of the server's 71 tools your prompts are really calling, and the one syntax trap that breaks the command the moment you add a flag to it.

TL;DR: claude mcp add playwright npx @playwright/mcp@latest connects Playwright MCP - no sign-in, no key. Confirm it with claude mcp list. It exposes 71 tools total, but only 24 (core browser actions plus tab management) load by default; the rest sit behind --caps flags. The moment you add a flag of your own to the install command - --headless, --browser=firefox - you need -- before npx or Claude Code misreads the flag as its own and errors out.

What Playwright MCP gives Claude Code

Playwright MCP wraps Microsoft's Playwright browser automation library as a Model Context Protocol server, so Claude Code can drive Chrome, Firefox, WebKit, or Edge directly instead of you copy-pasting what a page shows. The detail that matters more than "it controls a browser" is how it reads the page: it works off Playwright's accessibility tree, not screenshots. That's why Claude can tell you a button is disabled or a form field is missing a label without a vision model in the loop - it's reading structured page data, the same data a screen reader would use, not guessing from pixels.

Microsoft also ships a different path for agents, and it isn't a footnote. Playwright's own README now points coding agents toward microsoft/playwright-cli, a CLI+SKILLS approach, before it points them at MCP. I get into why, and when the alternative wins, in the limits section below.

Install it: one command

claude mcp add playwright npx @playwright/mcp@latest

That's the exact line from Playwright's own MCP docs and from microsoft/playwright-mcp's README - both point Claude Code users at the same command, no --transport flag because it runs as a local stdio process, not a hosted one. It needs Node.js 18 or newer and nothing else: no account, no API key, no browser tab to authorize.

By default that writes the server at local scope - private to you, in whichever project directory you ran the command from. If you test in more than one repo, add -s user instead so it follows you everywhere without re-adding it, the same scope flag any MCP server in Claude Code uses; the MCP config generator builds the whole command, scope flag included, if you'd rather pick Playwright from a list than type it by hand. Claude also lists a Playwright plugin in its own directory, installed through Claude Code's plugin marketplace rather than a raw mcp add call - functionally it wires up the same MCP server, so this guide sticks with the direct command, which is also the one both official docs pages point to.

Confirm it actually connected

Writing the config isn't the same as the server working. I ran this exact sequence for this guide, on Claude Code 2.1.259 with @playwright/mcp 0.0.80: claude mcp add playwright npx @playwright/mcp@latest printed Added stdio MCP server playwright with command: npx @playwright/mcp@latest to local config, which only confirms the write. claude mcp list is what checks the connection - it came back playwright: npx @playwright/mcp@latest - ✔ Connected within a few seconds, no browser window opened yet, because nothing has asked the server to launch one. claude mcp get playwright gives the same status plus the resolved command and args, useful when you're not sure which scope a server landed in.

If claude mcp list instead shows the server missing entirely in a new terminal or project, it's almost always the scope: local (the default) is tied to the exact directory you ran add from, so it won't show up in a sibling project or a fresh clone.

What you can ask it to do

You don't need to name tools in your prompt - Claude reads the task and picks from the 71 available on its own. What matters is which ones actually fire, because it changes how you phrase a follow-up. A vague "check the page" tends to pull browser_snapshot (the full accessibility tree); if you specifically want a picture to look at rather than structured data, ask for a screenshot by name, since browser_take_screenshot and browser_snapshot solve different problems and Claude can't always tell which one you mean from "look at the page."

The last row - recording a flow and getting real Playwright code back - is the one most people don't discover on their own. browser_start_recording captures every action Claude (or you, narrating a manual flow) takes as executable Playwright code, and browser_stop_recording hands it back. It turns "here's a bug I found by clicking around" into a runnable regression test in the same conversation, no separate codegen step.

All 71 tools, and which ones need an opt-in flag

Playwright's own docs describe the server only as providing "tools for all common browser interactions" without a count - I counted them by hand from microsoft/playwright-mcp's README instead, since neither that page nor any of the setup posts already ranking for this topic itemize it. Two groups - core automation and tab management, 24 tools - load with no flags at all. Everything else needs its capability named at install time:

To turn one on, add the flag - and this is where the -- rule from the TL;DR actually bites. claude mcp add playwright npx @playwright/mcp@latest --caps=testing doesn't work; Claude Code reads --caps as trying to be one of its own options and rejects it. The working form inserts -- right before npx:

claude mcp add playwright -- npx @playwright/mcp@latest --caps=testing

Common setup issues

I hit three things worth flagging before you do:

• Any flag after the package name needs -- first. I tested this directly: running claude mcp add playwright npx @playwright/mcp@latest --headless (no --) fails immediately with error: unknown option '--headless' (Did you mean --header?) - Claude Code's own arg parser grabs it before it ever reaches the Playwright process. Add -- right before npx and the same command works and shows Connected. The base install command has no flags of its own, so it doesn't need -- - the trap only shows up once you add one.
• Two Claude Code sessions in the same project fight over the browser profile. Playwright MCP's persistent profile (the default) can only be driven by one browser instance at a time, so a second concurrent session in the same workspace will collide with the first. Add --isolated to one of them, or point each session at its own --user-data-dir, and they stop stepping on each other.
• Headless environments (CI, containers, a server with no display) need --headless and usually --no-sandbox. Playwright MCP runs headed by default. Microsoft also ships an official Docker image (mcr.microsoft.com/playwright/mcp) that only runs headless Chromium, which is the simpler route if you're already containerizing the run.

When Playwright MCP isn't the right call

If Claude Code is doing high-volume coding work and only occasionally needs to poke at a browser, 71 tools' worth of schema landing in context on every connected turn is a real cost - read up on what that costs you before you leave it connected by default in every project. Microsoft's own README makes a version of this same argument for coding agents specifically: it now points toward CLI+SKILLS instead of MCP, because a CLI invocation skips loading the tool schemas and accessibility trees into the model's context that MCP pays on every call. Reach for the MCP server when you want persistent state across a long, exploratory session - self-healing tests, iterative debugging where Claude keeps the same browser tab open across many turns - and reach for CLI+SKILLS when you mostly want one-off checks without the standing context cost.

It's also not a replacement for a real test suite. Playwright MCP is built for Claude to drive a browser interactively inside a conversation, not to run your CI's regression suite - the recording tools get you a starting point for a test file, not a maintained one.

FAQ

What's the exact command to connect Playwright MCP to Claude Code?

claude mcp add playwright npx @playwright/mcp@latest - it's the exact command Playwright's own docs and the microsoft/playwright-mcp README both show for Claude Code. No transport flag and no scope flag needed; it defaults to a stdio server in local scope.

Does Playwright MCP need Node.js or any API keys?

Node.js 18 or newer, and nothing else. There's no API key, no OAuth sign-in, no account - claude mcp add writes the config, and the next time Claude calls a browser tool, npx fetches and runs @playwright/mcp for you.

How many tools does Playwright MCP actually expose?

71, counted by hand from microsoft/playwright-mcp's own README. 23 core automation tools plus 1 tab-management tool load by default; the other 47 - storage, devtools, network, coordinate-based control, PDF export, and test assertions - are opt-in behind a --caps flag.

Why do I need "--" before npx when I add extra flags?

Because without it, Claude Code tries to parse a flag like --headless as one of its own claude mcp add options and fails with error: unknown option '--headless' - tested for this guide. The plain claude mcp add playwright npx @playwright/mcp@latest command doesn't need -- since it has no flags of its own; the moment you add one, insert -- right before npx: claude mcp add playwright -- npx @playwright/mcp@latest --headless.

Should I use Playwright MCP, or Playwright's CLI+SKILLS instead?

For a coding agent like Claude Code, Playwright's own README now recommends trying microsoft/playwright-cli's CLI+SKILLS approach first - it skips loading MCP's large tool schemas and accessibility trees into context. Reach for the MCP server specifically when you want persistent browser state across a long conversation or exploratory, self-healing testing where that overhead is worth it.

The command is the small decision

Everything past claude mcp add is Claude reading a page the way a screen reader would, instead of you narrating what's broken from a browser tab it can't see. Which MCP servers are worth leaving connected by default - Playwright included - is exactly the call ClockedCode's own curated list makes for you, along with a tuned CLAUDE.md that already knows not to double up a server your plugins provide another way.