You ask Claude Code why the signup flow breaks, and it can only guess from the source. So you open the page, click through it yourself, copy what you see, and describe it back in words. The agent is working from your summary, not the page.
Playwright MCP takes you out of that loop. It’s Microsoft’s official browser automation server: it lets Claude Code open a real browser, click through a page, read the actual rendered text, and fill in forms, using accessibility snapshots instead of pixel screenshots. It’s become one of the most-installed MCP servers because it turns “describe this page to me” from a guess into an actual read. Setup takes about 2 minutes.
Add it as a local stdio server — no separate install step, npx handles it on first run.
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest
Restart Claude Code, then run /mcp inside a session to confirm it shows as connected. Total time: about 2 minutes.
Skip Steps 1-4 below and hand the whole thing to the agent instead:
You have access to the `claude mcp` CLI in this project. Do the following and report back — do not tell me it's done unless step 4 actually confirms it:
1. Run `claude mcp list` to see what's already configured.
2. Add the Playwright MCP server: `claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest`
3. Run `claude mcp list` again and confirm playwright shows as Connected.
4. Open a real page to prove it works: navigate to https://example.com and read back the page's main heading text. If step 4 fails, tell me the exact error instead of reporting success.
This works because Claude Code can run its own CLI commands and then immediately use the newly connected server — so the agent proves the browser actually works instead of just confirming the config exists.
| Requirement | Why You Need It | Time |
|---|---|---|
| Claude Code installed | Provides the claude mcp command used to register the server |
0 min |
| Node.js | Playwright MCP runs via npx — no separate download needed beyond this |
~5 min if missing |
| ~300MB free disk space | First run downloads a Chromium build for Playwright to drive | ~1 min |
Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.
~1 min
The -- separates Claude’s own flags from the command that launches the server:
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest
By default the browser runs headed (a visible window). For faster, invisible runs — especially useful when Claude Code is doing background verification work — add --headless and --isolated so each session starts from a clean profile instead of reusing saved cookies:
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest --headless --isolated
Defaults to Chromium. To test against Firefox or WebKit instead, pass --browser:
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest --browser firefox
Run claude to start a fresh session. Newly added servers need a restart (or the /mcp panel refresh) before Claude Code can see their tools.
Claude Code drives a real browser: it clicks, types, and reads the rendered page.
| Flag | What It Does |
|---|---|
--headless |
Runs the browser with no visible window — headed (visible) is the default |
--isolated |
Keeps the browser profile in memory only, so every session starts fresh instead of reusing saved logins/cookies |
--browser |
Chooses the engine: chromium ,firefox ,webkit , ormsedge |
--vision |
Switches from accessibility snapshots to actual screenshots — slower and less reliable, only use it if a page genuinely needs visual inspection |
--device |
Emulates a specific device, e.g. "iPhone 15" , for responsive/mobile testing |
Check that it’s registered and healthy:
claude mcp list
✔ playwright Connected
✘ playwright Failed to connect
A config entry showing up is not the same as it working — the real test is asking Claude Code to actually drive the browser. In a session, ask it to navigate to a real page and read something back:
Navigate to https://example.com using the playwright MCP tools and tell me the exact text of the page's main heading.
If it comes back with the actual heading text (“Example Domain”), the browser is genuinely working end to end — not just listed as connected.
-- separator.claude mcp list.--headless or the browser launch will fail.--vision by default./mcp panel refresh to pick up a newly added server.
No, by default it reads the page’s accessibility tree (an accessibility snapshot) rather than capturing pixels — that’s faster and lets Claude read actual text and structure instead of interpreting an image. Screenshots are only used if you pass --vision.
Not if you use --isolated — that keeps each session’s profile in memory only. Without it, Playwright MCP uses a persistent profile stored in a separate cache directory, not your regular browser’s profile.
Yes — that’s one of the most common uses: ask Claude Code to navigate your local dev server or a staging URL, click through a flow, and report back what it actually saw rendered.
Usually a missing display for headed mode — add --headless, and if Chromium itself is missing in the CI image, its first-run download step needs network access.
Yes — claude mcp remove playwright deletes it from the config.
claude mcp command reference
Originally published at quickpromptco.com, where the guide is kept up to date.