Most agent frustration on frontend work comes down to one gap: the agent edits a component, says it’s done, and has no idea whether the page actually renders. The Playwright MCP server closes that gap. With it connected, Claude Code can open a real browser, click through your change, and confirm the result before claiming success.
This guide shows how to add it, what it can do, and the verify-my-change loop that makes it useful day to day. It also covers headless versus headed mode and the Windows and WSL specifics, since browser automation is where the two environments diverge most.
If you’re still setting up MCP in general, start with the MCP setup guide for Windows and WSL.
What it can actually do
The server exposes browser actions as tools Claude can call. In practice that means:
- Navigate to a URL and wait for the page to load
- Click buttons and links, fill form fields, submit forms
- Read the page — text content, the accessibility tree, element state
- Screenshot the full page or a specific element
- Assert that something is present, visible, or has the expected text
That last group is the point. Claude can check its own work instead of handing you a change and hoping.
Install the server
The Playwright MCP server runs through npx. Add it to Claude Code:
claude mcp add playwright -- npx -y @playwright/mcp@latestOn native Windows PowerShell, npx-based servers sometimes need a command wrapper to launch correctly:
claude mcp add playwright -- cmd /c npx -y @playwright/mcp@latestThe first run downloads browser binaries, which takes a minute. If you’ve never installed Playwright on this machine, you may also need its browsers and dependencies — the Playwright installation docs cover the per-OS steps.
npx playwright install --with-depsConfirm the connection with claude mcp list, or run /mcp inside a session to see the Playwright tools.
The verify-my-change loop
Here’s the workflow that makes this worth installing. Start your dev server, then ask Claude to make a change and check it:
The submit button on /signup isn't disabling while the form is in flight.
Fix it, then open the page in a browser and confirm the button disables
after I click submit. Screenshot the disabled state.What happens next is the difference from a normal agent session. Claude edits the component, navigates to the page through Playwright, clicks submit, reads the button’s state, and reports back with a screenshot of the disabled button. If it didn’t work, it sees that too and keeps going.
You can make this a standing expectation:
After any change to a page under /dashboard, load it in the browser and
confirm it renders without console errors before telling me it's done.That turns “I updated the layout” into “I updated the layout and verified it renders,” which is a much more useful kind of done. For more patterns like this, see the Claude Code power-user guide.
Headless vs headed
Two modes, and the choice is simple once you know what each is for.
Headless vs headed
| Headless (default) | No visible window; fast; best for verification and CI-style checks |
|---|---|
| Headed | Visible browser; watch actions live; best for debugging a flaky interaction |
| On WSL | Headless works out of the box; headed needs a display (WSLg/X server) |
| Day to day | Stay headless and let Claude screenshot; switch to headed only to debug |
Headless is the right default. You don’t need to watch the browser to trust a screenshot and an assertion, and headless is faster and works everywhere. Reach for headed only when an interaction behaves oddly and you want to see it happen.
Windows and WSL notes
This is where the two environments split.
On WSL, headless Playwright is the smooth path. Install the browsers and their Linux dependencies inside the distro with npx playwright install --with-deps, run headless, and let Claude screenshot when you want to see the result. Headed mode works only if you have WSLg or an X server providing a display, so unless you specifically need a visible window, stay headless.
On native Windows, both headless and headed work without a display server, but remember the cmd /c wrapper on the add command if the server fails to launch. The browsers install under your user profile.
Playwright MCP setup checklist
- Add the server with claude mcp add (use cmd /c on native Windows)
- Run npx playwright install --with-deps the first time
- Verify with claude mcp list or /mcp
- Start your dev server and note the local URL
- Stay headless unless you're debugging a flaky interaction
- On WSL, only attempt headed mode if you have WSLg/X
- Point it at local or staging, never production
Wrapping up
The Playwright MCP server is the cheapest way to make Claude Code accountable for frontend changes. Add it per-project, keep it headless, run your dev server alongside, and ask Claude to verify what it changes. The result is fewer “looks done but isn’t” moments and a tighter loop between edit and confirmation.
It’s one of a small set of servers genuinely worth the context — see the rest in the best MCP servers for Claude Code in 2026.
