If you searched "Claude Code + Playwright," the first thing you probably found was the Playwright MCP server — it's the original, most widely documented integration. But there's a newer option, Playwright CLI, built specifically for agents like Claude Code that already have shell access. They solve the same problem in very different ways, and picking the wrong one for your situation can cost you real time and real tokens.
This post breaks down exactly how they differ, with real numbers, so you can pick the right tool for your project.
claude mcp add playwright npx @playwright/mcp@latest
Playwright MCP is a Model Context Protocol server that gives Claude tools like browser_navigate
, browser_click
, and browser_snapshot
. It's the plug-and-play option:
claude mcp add playwright npx @playwright/mcp@latest
Playwright CLI is a newer, standalone command-line tool built for coding agents that already have filesystem and shell access:
npm install -g @playwright/cli@latest
npx playwright install chromium
grep
), instead of the whole document.Here's identical logic — navigate, fill a field, submit, verify — expressed through each tool.
With MCP (called as conversational tool-use, no shell commands visible):
Claude calls: browser_navigate(url="https://demo.playwright.dev/todomvc")
Claude calls: browser_snapshot()
Claude calls: browser_type(ref="e12", text="Write blog post")
Claude calls: browser_press_key(key="Enter")
Claude calls: browser_snapshot()
With CLI (run as literal shell commands):
playwright-cli navigate https://demo.playwright.dev/todomvc
playwright-cli snapshot
playwright-cli fill e12 "Write blog post"
playwright-cli press e12 Enter
playwright-cli snapshot
This is the part that actually matters for your wallet and your context window. Independent benchmarking on a typical multi-step browser task found:
| Tool | Approx. Tokens for a Multi-Step UI Test |
|---|---|
| Playwright MCP | ~114,000 |
| Playwright CLI | ~26,000–27,000 |
That's close to a 90,000-token difference for the same task — largely because MCP re-sends full page state into the conversation on every single tool call, while CLI keeps that state on disk and Claude only pulls in the specific slice it needs.
For a one-off exploratory test, this difference barely matters. For a full regression suite, or a long session where you're testing form after form, it's the difference between finishing your session and hitting a context limit halfway through.
| Use MCP when... | Use CLI when... |
|---|---|
| Your agent is sandboxed with no shell access (Claude Desktop, custom chat UI) | Your agent has shell/filesystem access (Claude Code, Copilot, Cursor) |
| You need quick, exploratory, one-off browser tasks | You're running long, multi-step sessions where token budget matters |
| You want conversational back-and-forth over page structure | You want repeatable automation you can also run in CI |
In practice, most teams don't pick just one — they keep CLI as the default for test writing and longer sessions, and leave MCP configured as a fallback for quick interactive debugging when a shell isn't convenient.
Playwright MCP and Playwright CLI aren't competitors so much as tools for different moments — MCP for sandboxed, conversational exploration, and CLI for token-efficient, repeatable automation with an agent that already has shell access. Now that you know the tradeoffs, in the next post we'll go further into general token-saving habits for Claude Code sessions — beyond just this one tool choice.
Which one are you already using — MCP, CLI, or both? Let me know in the comments!