Last Verified: October 2026 — commands, flags, and error messages checked against the microsoft/playwright-mcp docs
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.
How it works
Measured by us · October 22, 2026
Windows 11 laptop (build 26200), Node 24.18.1. Our own script sent the two requests any MCP client makes to learn what a server offers (initialize, then tools/list) and timed the answer. No Claude Code session, no account, no API key.
| What we checked | Result |
|---|---|
| Server version | Playwright 1.64.0-alpha-1790635538000 |
| Tools it adds | 25: browser_close, browser_resize, browser_console_messages, browser_handle_dialog, browser_emulate_media, browser_evaluate, browser_file_upload, browser_drop, and 17 more |
| Size of the tool definitions | 20.8 KB, about 5,330 tokens |
| Time to answer | 16.5 s on our first launch of the day, 5.8 s on the next one |
| Change since our October 3 run | Same tools; definitions unchanged (5,333 → 5,333 tokens) |
Tokens are estimated as characters ÷ 4, the same way as in our other measured posts; we didn’t run a tokenizer. This is what the server costs when it loads, not a whole session, and Claude Code’s tool search can defer MCP tool definitions until they’re needed, so treat it as the worst case.
Quick Start
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@latestRestart Claude Code, then run /mcp inside a session to confirm it shows as connected. Total time: about 2 minutes.
⚡ Copy This Prompt: Let Claude Code Install and Verify It For You
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.
On this page (8 sections)
Before You Add Playwright MCP
| 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 |
| Google Chrome (or another browser) | By default Playwright MCP drives your installed Chrome. No Chrome? Install it, or pick Firefox or WebKit with --browser |
0 min |
Step-by-Step Setup
Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.
Step 1 — Add the server
~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
--scope the server lands in local config: this project only, and only on your machine. Add --scope user to use it everywhere.Step 2 — Run it headless (optional, faster in CI or background use)
~1 min
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 --isolatedStep 3 — Pick a specific browser engine (optional)
~1 min
Defaults to your installed Google Chrome (the chrome channel). To test against Firefox or WebKit instead, pass --browser:
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest --browser firefoxStep 4 — Restart and approve
~1 min
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.
What Each Flag Does
| 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: chrome (default), firefox, webkit, or msedge |
--caps vision |
Adds coordinate-based mouse tools (click at x,y) for elements the accessibility tree can’t describe. Replaces the old --vision flag. Other opt-in caps: pdf, devtools |
--device |
Emulates a specific device, e.g. "iPhone 15", for responsive/mobile testing |
Check Playwright MCP Is Really Connected
Check that it’s registered and healthy:
claude mcp list✘ 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.
Playwright MCP Not Connecting? Fixes for Common Errors
Most failures happen before a browser ever opens: the npx process exits, Claude Code shows Failed to connect or connection_closed, and the real error stays hidden. Run the package yourself first. If this prints the flag list, Node.js, npx, and the package are fine:
npx -y @playwright/mcp@latest --help| What You See | Usual Cause | Fix |
|---|---|---|
✘ playwright Failed to connect | npx couldn’t start the server: Node.js missing or old, or the package download was blocked | Check node -v and run the --help command above. On native Windows, if npx works in your terminal but not from Claude Code, re-add it through cmd /c: claude mcp add --transport stdio playwright -- cmd /c npx -y @playwright/mcp@latest |
failed to reconnect to plugin:playwright:playwright: connection_closed | The same server installed as a Claude Code plugin (plugin servers are named plugin:<plugin>:<server>) exited on startup | Same checks as above, then reconnect from /mcp. If you also added it with claude mcp add, remove one copy so two servers don’t share one browser profile |
Browser "chrome" is not installed | The default engine is your installed Google Chrome | Install Chrome, run the install command the error prints (npx @playwright/mcp install-browser <browser>), or switch with --browser firefox |
Browser is already in use for <userDataDir> | Another session is holding the saved browser profile | Close the other session, or add --isolated so each session gets its own in-memory profile |
Missing system dependencies required to run browser | Linux or CI image without the browser’s shared libraries | sudo npx playwright install-deps chrome, and add --headless when there’s no display |
Common Mistakes to Avoid
- Forgetting the
--separator. Without it, Claude Code can’t tell where its own flags end and the server’s launch command begins. - Assuming “Connected” means the browser itself works. The MCP handshake can succeed even if the first real navigation later fails — always test with an actual page load, not just
claude mcp list. - Running headed by default in a CI or background context. If there’s no display available, add
--headlessor the browser launch will fail. - Turning on
--caps visionby default. Accessibility snapshots handle almost every page, and clicking by coordinates breaks as soon as the layout shifts. Only add it when an element genuinely isn’t in the accessibility tree. - Not restarting after adding the server. Claude Code needs a fresh session or an
/mcppanel refresh to pick up a newly added server.
Q&A
Does this take screenshots of every page?
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. It only takes a screenshot when the agent calls the screenshot tool, for example when you ask it to capture the page.
Will this affect my regular browser’s saved logins?
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.
Can I have the agent test my own site with this?
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.
Why does it fail in a CI environment?
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.
How do I add Playwright MCP to Claude Code?
Run claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest, restart Claude Code, and check /mcp. Microsoft’s README uses the shorter claude mcp add playwright npx @playwright/mcp@latest, which registers the same server. Add --scope user to use it in every project.
Playwright MCP or a Puppeteer MCP server?
Playwright MCP. It’s Microsoft’s actively maintained server, drives Chrome, Firefox, and WebKit, and reads pages through accessibility snapshots. The original reference Puppeteer MCP server was archived by the MCP project, so it no longer gets fixes.
Can I remove it later?
Yes — claude mcp remove playwright deletes it from the config.
Official Resources
- microsoft/playwright-mcp on GitHub — source, full flag reference, and issue tracker
- Playwright MCP Documentation — official getting-started guide
- Claude Code MCP Documentation — the
claude mcpcommand reference
If this guide got your first browser-driving MCP server connected, follow us on X for more setup guides and prompt tips.
Comments
4 responses to “How to Add Playwright MCP to Claude Code: Real Browser Automation in 2 Minutes (+ Connection Fixes)”
[…] already have their own dedicated setup guides — see Playwright MCP, GitHub MCP, and Context7 […]
[…] runs as an independent MCP connection. If you use Playwright or GitHub MCP alongside these, see our Playwright MCP guide and GitHub MCP guide for the same install […]
[…] using our Playwright MCP setup? The two are complementary. Playwright is built for driving the browser through flows. DevTools MCP […]
[…] uses GitHub and Playwright as the example servers. If you set up Playwright the direct way with our Playwright MCP guide, this is the containerized […]