Draft, pending test: written from current vendor docs. We have not run this workflow end to end yet, so nothing below is a measured result. Not indexed.
Playwright MCP: set it up and have Claude Code test your web app
Add Microsoft's Playwright MCP server to your agent (for Claude Code: claude mcp add playwright npx @playwright/mcp@latest), point it at a local or staging URL, and ask it to walk a user flow step by step. It drives a real browser through accessibility snapshots, reports what broke, and can then write a regular Playwright test so the check runs in CI without the agent.
Who it's for & level
You build web apps (by hand or with an AI coding agent) and you already use Claude Code or Cursor. You want the agent to check its own work in a browser instead of telling you it 'should work', without writing a test suite first.
- Level
- intermediate
- Tools
- Roles
- Developers Vibe coding
- Goals
- Ship an app
- Tasks
- Testing
- Time to set up
- 10–20 min to connect, 15–30 min for the first useful run (est.)
- Cost
- Playwright MCP is free and open source (Apache-2.0). You pay only for your agent's usage (Claude plan/API or Cursor plan). Accessibility snapshots of big pages use a lot of context, so long sessions cost more tokens (est.).
- Time saved
- 15–45 min per manual click-through of a changed flow (est.) (est.)
- Test status
- Pending test
- Last verified
- pending test
- Model versions
- n/a
- Written by
- Usecased editorial (pending test) (agent)
- Published
- 2026-10-15
Prerequisites
- Node.js 18 or later (the server runs with npx).
- Claude Code or Cursor installed. Any MCP client works; config differs.
- A local dev server or a staging URL you're allowed to test. Not production with real customer data.
- A throwaway test account for any flow that needs login.
- Optional: @playwright/test in the repo if you want the agent to save the run as a test.
The problem
AI coding agents write UI code they never see. They say the signup form works, and you find the broken button yourself. Writing end-to-end tests up front feels heavy for a prototype, and screenshot-based computer-use agents are slow and miss things. You want the agent to actually open the page, use it like a person and tell you what failed.
Steps
- Add the server to your agent. In Claude Code run claude mcp add playwright npx @playwright/mcp@latest (add -s project to share it via .mcp.json). In Cursor add the same command under Settings > MCP or in .cursor/mcp.json. Restart the client and check the server shows as connected with tools like browser_navigate, browser_snapshot and browser_click.
- Choose headed or headless. Headed (the default) lets you watch the browser, which is what you want for the first runs. Add --headless once you trust it, and --isolated so each session starts with a clean profile instead of reusing cookies.
- Start your app and write the flow down. Run your dev server. Write the flow as numbered user actions with an expected result for each step. Vague asks ('test my app') produce vague wandering.
- Ask for a walkthrough, not a fix. Use the walkthrough prompt below. Tell the agent to report and stop at the first failure rather than edit code, so you see the bug before it 'fixes' it.
- Check the evidence. Ask for a screenshot at the failing step (browser_take_screenshot) and the console messages. Compare with what you see in the headed window. Snapshots can miss purely visual bugs such as overlap or contrast.
- Fix, then re-run the same flow. Now let the agent fix the bug in code and re-run exactly the same walkthrough. Same prompt, same data, so you're comparing like with like.
- Turn it into a real test. Ask the agent to write the flow as a @playwright/test spec using role-based locators, then run npx playwright test. The spec runs in CI with no AI, no tokens and no randomness.
Exact prompt & config
claude mcp add playwright npx @playwright/mcp@latest
# shared with the team via .mcp.json:
claude mcp add -s project playwright -- npx @playwright/mcp@latest --isolated
# inside claude: /mcp -> playwright should be listed as connected
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--isolated"]
}
}
}
Use the playwright MCP tools. Don't edit any code in this task.
App: http://localhost:3000. Test account: test+e2e@example.com / see .env.test (don't print the password).
Walk this flow and check each expected result:
1. Open /signup. Expect a form with email, password and a "Create account" button.
2. Submit with an invalid email. Expect an inline error, no navigation.
3. Submit valid details. Expect a redirect to /onboarding within 5 s.
4. Complete onboarding step 1 (pick any plan). Expect the dashboard with the user's email in the header.
For each step report: PASS/FAIL, what you saw, and any console errors.
Stop at the first FAIL, take a screenshot and tell me the likely cause. Don't retry more than twice.
Write the flow you just walked as tests/e2e/signup.spec.ts with @playwright/test.
Use getByRole / getByLabel locators, no CSS selectors or fixed waits.
Read credentials from process.env. Run npx playwright test tests/e2e/signup.spec.ts and show me the result.
Sample output
Example output, written to show the expected shape. Not captured from a real run yet.
(Example of the expected shape, not a captured run)
1. /signup form present ............................ PASS
2. Invalid email shows inline error ................ PASS ("Enter a valid email")
3. Valid submit redirects to /onboarding ........... FAIL
Saw: button shows a spinner, URL stays /signup after 5 s.
Console: POST /api/signup 500 — "relation users_profile does not exist"
Screenshot: signup-step3.png
Likely cause: the profile table migration hasn't been applied locally.
Stopped at step 3 as instructed.
Why MCP instead of ‘just write tests’
For a changing prototype, writing and maintaining end-to-end tests is the step everyone skips. Playwright MCP flips the order: the agent walks the flow first, in plain English, against the app as it is today. Once the flow is stable, you freeze it into a spec. You get bug reports immediately and a regression test later, without having to write the test first.
It also closes the loop for vibe-coded apps. An agent that can open the page it just changed tends to catch its own mistakes: a 500 from the API, a redirect that never happens, a button that isn’t wired up.
The loop that keeps you in control
- Describe the flow as numbered actions with expected results.
- Walk it with the agent, code edits forbidden, stopping at the first failure.
- Check the screenshot and console yourself.
- Fix in a separate step, then re-run the same walkthrough.
- Freeze the flow into a
@playwright/testspec and run it in CI.
Keep the agent on localhost or staging, with test accounts. Anything it can see, it can click.
Going further
Run the same walkthrough prompt after every agent-made change as a habit, or put it in a project command. Add a second flow for the thing that breaks most often (checkout, password reset). When a page is hard for the agent to use, run an accessibility check: the same missing labels that trip the agent trip real users.
How it went
Pending test. What we expect, based on the vendor docs and public reports below. This becomes a measured result after our run.
Expected result, pending our test: on a simple form flow the agent should complete the walkthrough and catch functional failures (server errors, missing redirects, broken buttons) reliably, and miss purely visual problems unless you ask for screenshots. We'll record how many steps it got right, where it wandered, the token use of a full run and whether the generated spec passed on first try.
Worth knowing
- It works from accessibility snapshots, not pixels. Layout, overlap and contrast bugs can pass unnoticed. Ask for screenshots or add a visual check.
- Pages with poor accessibility (div buttons, no labels) are harder for the agent to target, the same way they are for screen readers. That's also a real bug worth fixing.
- Snapshots of big pages are large and eat context. Keep each session to one flow.
- The default profile persists cookies between sessions. Use --isolated for repeatable runs.
- Agent runs aren't deterministic. Use them to explore and find bugs; use a saved @playwright/test spec as the regression check.
- The agent can type into any page it reaches. Don't point it at production admin panels or give it real credentials, and treat page content as untrusted input (prompt injection).
- Playwright also ships a CLI with agent skills; for coding agents with a shell that can be lighter on context than MCP. Both are covered in our Claude Code skills smoke-test case.
FAQ
What is Playwright MCP?
An official Model Context Protocol server from Microsoft that exposes Playwright browser actions (navigate, click, type, snapshot, screenshot) as tools, so an AI agent like Claude Code, Cursor or VS Code Copilot can drive a real browser.
How do I add Playwright MCP to Claude Code?
Run claude mcp add playwright npx @playwright/mcp@latest, then check /mcp inside Claude Code. Add -s project to save it in .mcp.json for your team.
Does Playwright MCP use screenshots?
By default it uses accessibility snapshots, a structured text view of the page, which is faster and more precise for clicking. It can also take screenshots when you ask for visual evidence.
Can Playwright MCP replace my end-to-end tests?
No. Use it to explore flows and find bugs, then have the agent write a normal Playwright test for the flow so CI can run it deterministically without an AI.
Is Playwright MCP free?
Yes, it's open source. You only pay for the AI agent that calls it.
Related use cases
- Claude Code skills: build a /smoke-test skill that clicks through your web app in a real browser
- n8n MCP server: build, test and publish n8n workflows from Claude Code
- Cursor MCP: connect your first MCP servers [draft, pending test]
- Cursor rules: a .cursor/rules setup that keeps the agent consistent in your repo [draft, pending test]