Last Verified: September 2026 — commands and maintenance status checked against live GitHub sources
Playwright MCP is 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 precisely because it turns “describe this page to me” from a guess into an actual read.
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.
What You’ll Need
| 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 |
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@latestStep 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 Chromium. 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: chromium, firefox, webkit, or msedge |
--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 |
Verify the Connection
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.
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. - Reaching for
--visionby default. Accessibility snapshots (the default) are faster and more reliable than screenshots for almost every task — only switch to--visionwhen a page’s layout genuinely can’t be understood from its 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. Screenshots are only used if you pass --vision.
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.
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.
Leave a Reply