If you've wired up the Playwright MCP server with Claude Code and watched it spend a hundred thousand tokens to write a login test, you've already met both sides of this setup.
The pairing is genuinely useful for some things and breaks predictably on others. What follows is a frank account of both, grounded in token benchmarks, GitHub issues, and our own experience building browser testing on this stack, not another install tutorial.
The short version: Playwright MCP gives Claude Code a real browser, so it can author and debug tests against your live app instead of guessing from your source files. It's good at first-pass authoring, selector refactors, and debugging, and it struggles with long tests, OAuth, and token cost. Here's where each line falls.
What this setup actually does
The Playwright MCP server hands Claude Code a real browser. Claude navigates pages, clicks elements, fills forms, and reads the accessibility tree, the structured representation of what's on the page. Instead of reasoning about your test from code alone, it interacts with your live app and grounds its output in what it actually sees.
The most common use: ask Claude to write a test, and it opens a browser, walks the test, and produces locators based on the real DOM rather than a guess from source. That's the promise. It mostly holds, until it doesn't.
What works reliably
The setup earns its reputation in four situations.
First-pass authoring on simple tests. Need a test for a login page, a signup form, or a basic create-read-update-delete test? Claude Code plus Playwright MCP gets you working code faster than writing it by hand, and the locators are grounded in the live DOM, so you get fewer "element not found" failures on the first run.
Selector refactoring. If you have tests held together by fragile data-testid or XPath selectors, Claude can walk the live page and suggest getByRole() or getByLabel() replacements that survive a markup change. This is some of the most reliable value in the stack.
Debug loops on a known failure. Point Claude at a failing test, let it run the test in a browser, and it can often tell you whether the cause is a moved selector, a timing issue, or a real regression, faster than reading a trace file cold.
Throwaway exploration. When you just need to understand what a page does or what a test looks like, letting Claude poke at it live is quicker than reverse-engineering the component tree.
The token problem
Here's the number most tutorials skip. By one widely-shared benchmark, running a test through Playwright MCP costs roughly 114,000 tokens. The same test generated through the Playwright CLI, with Claude writing code without a live browser, costs about 27,000 tokens. Roughly a 4x difference, and it compounds.
The reason: after every navigation, the MCP server sends Claude a full accessibility-tree snapshot of the current page. On a content-heavy page, one snapshot can run to 50,000 tokens on its own, a problem developers have tracked on the Playwright MCP repo. By step twelve of a test, the context window is carrying snapshots from screens Claude already left.
What that means in practice:
- Long tests hit the context limit. Past roughly twenty steps you start bumping into the context window. When that happens, compaction kicks in, and compaction can scramble test state, so the agent loses track of where it is.
- Cost scales with test length, not difficulty. A fifteen-step checkout costs more than a five-step API test with hairy assertions.
- The CLI is cheaper for code you'll keep. If the goal is Playwright code you commit and run in CI, generating it without a live browser uses far fewer tokens and is more repeatable.
MCP earns its cost when you specifically need Claude to interact with a live browser in real time. For sustained authoring, the CLI is the more practical tool.
What breaks
OAuth and MFA. The MCP server doesn't carry session state across a third-party auth redirect by default. Google OAuth, GitHub login, magic links, OTP: they all send the agent off your domain and back, and the session doesn't survive the trip. You can complete auth by hand, save the storage state to a file, and inject it, but that's manual setup you redo every time the session expires.
Shadow DOM, iframes, and lazy content. Elements inside shadow roots or iframes don't show up in the standard accessibility tree, and neither does content that hasn't scrolled into view. Claude will try to act on things it can't see, generate locators that fail at runtime, and sometimes loop looking for content that isn't in the tree yet.
Nondeterminism. Two sessions running the same test on the same page can land on different locators and different assertions. There's no guarantee the test you got today matches the one you'd get tomorrow, which is a real problem if you care about consistent style across a suite.
Branching tests. "If the user has no projects, click create; otherwise open the one named Test" is the kind of thing Claude handles fine in conversation but generates shaky code for. Conditional logic usually needs real editing before it's trustworthy.
When to use MCP, and when to use the CLI
When people search "claude playwright" they usually mean one of two workflows, and the right tool differs.
| Reach for | When you're |
|---|---|
| MCP (browser mode) | debugging a specific interaction live, generating locators for a page that's hard to read from code, or exploring what a page does |
| CLI (code mode) | generating test files for tests you already understand, refactoring an existing suite, or writing test helpers |
The distinction is simple. MCP is for seeing what's happening. The CLI is for writing code about what happens. They're complementary, not competitors.
Other ways to hand an agent a browser
Playwright MCP isn't the only option, and which one fits depends on how much you want to own.
Claude Code can now drive a real Chrome instance directly, which is handy if you'd rather not maintain Playwright at all. You skip the framework and let the agent work the browser you already have. There's also agent-browser from Vercel Labs, which is very lightweight and built specifically to give an LLM browser access. The catch with the lightweight, automated-browser approaches is the same one every scraper hits: they tend to get flagged as bots. The moment a real site decides your browser looks automated, you're fighting CAPTCHAs and blocks instead of testing your test.
None of these is strictly better. They trade convenience against control, and they all run on your machine, which turns out to be the actually hard part.
Running the browser is the hard part
Every guide above quietly assumes the same thing: a browser running on your laptop, where it just works. The moment you try to run that browser somewhere else (a CI runner, a VM, a server you spun up to do this on a schedule), you find out how much your operating system was doing for you.
A browser on a bare virtual machine is missing half of what your laptop ships by default. Fonts don't render. Logos and emoji come out as empty boxes. Pages look subtly wrong in ways that take days to chase down, because the thing rendering them is missing pieces your OS bundles and a clean VM doesn't. Then there's the rest of the tail: datacenter IPs that get flagged or blocked, device emulation that doesn't quite match real hardware, headless quirks that only show up under load.
I've spent those days. If you can afford a managed cloud browser, it's almost always the right call over running all of that yourself. The time you save not debugging font rendering on a VM is worth more than the bill.
That's the choice we made building Smoketest. Tests run in a real cloud browser through Playwright, so we're not maintaining browser infrastructure on a VM, and you're not maintaining a local MCP server or eating Claude token costs per run. You describe a test ("log in, add to cart, check out") and it runs after every deploy and on a schedule, with a recording, a transcript, and a pass/fail result for each run.
Use Claude Code and Playwright MCP when you're writing and debugging tests locally. It's good at that. Use something that runs in the cloud for the tests you need checked continuously, whether or not anyone's at a keyboard.
FAQ
What is the Playwright MCP server?
The Playwright MCP (Model Context Protocol) server is an open-source server that gives an AI model like Claude Code access to a real browser through Playwright. It lets the model navigate pages, click, fill forms, and read page state, so it can generate grounded test code or interact with a live app during a session.
How many tokens does Playwright MCP use per test?
By one widely-shared benchmark, about 114,000 tokens per test in browser mode, versus roughly 27,000 for the CLI approach where Claude writes Playwright code without a live browser. The gap comes from the accessibility-tree snapshot the server sends after every navigation step.
What tests break with Playwright MCP?
Third-party auth (OAuth, MFA, magic links), content inside shadow DOM or iframes, lazy-loaded content, tests longer than about twenty steps where the context window fills up, and branching logic that depends on user state.
Can Playwright MCP run in CI?
You can, but you're running a browser process, an MCP server, and a Claude Code session together in the pipeline, plus the token cost per run. For CI-triggered or scheduled runs, most teams find it cleaner to use a service that owns the browser infrastructure and stores run artifacts for you.
What's the difference between Playwright MCP and just using Playwright?
Plain Playwright is a test framework. You write code, run it in CI, read results. Playwright MCP is an AI-to-browser interface that lets a model drive a browser in real time. MCP is for authoring and debugging; plain Playwright is for running committed, repeatable suites.
How do I set up Playwright MCP with Claude Code?
Add the server with npx @playwright/mcp@latest and register it in your Claude Code MCP config (via the /mcp command or the config file). Once it's configured, Claude Code has browser tools in any session. Microsoft maintains the server; it's open source on GitHub. Smoketest runs the tests you'd otherwise script, in a real cloud browser, after every deploy, no MCP server or token bill to manage. See how it works.
