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.
Why This Comparison Matters
- Token cost adds up fast in long test-writing sessions — the wrong tool can burn your budget on a single flow.
- Not every environment supports both — sandboxed clients like Claude Desktop can't run CLI commands, so MCP is your only option there.
- CI pipelines behave differently than interactive chat sessions, and one of these tools fits CI workflows much better than the other.
- Knowing both means you're not locked into a single approach across your whole test suite.
Prerequisites
- Completed Part 1 of this series, with Playwright CLI installed and working.
- Claude Code installed and authenticated.
- (Optional, for comparison) Playwright MCP installed:
claude mcp add playwright npx @playwright/mcp@latest
Table of Contents
- What Is Playwright MCP?
- What Is Playwright CLI?
- Step-by-Step: The Same Test, Both Ways
- Token Usage Comparison
- Decision Table: Which One Should You Use?
- Conclusion
Step 1: What Is Playwright MCP?
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
- Once registered, Claude calls these tools directly inside the conversation — no shell access required.
- The full accessibility tree (and often screenshots) gets returned as part of the tool result, which means it's injected straight into the model's context.
- This makes MCP the right choice for sandboxed environments — Claude Desktop, custom chat UIs, or any client without terminal access.
Step 2: What Is Playwright CLI?
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
- Instead of streaming page state into the conversation, it writes a compact YAML snapshot to disk.
- Claude reads only the specific lines it needs from that file (often with
grep), instead of the whole document. - Because it's just shell commands, it works anywhere Claude Code already runs — locally or in CI.
Step 3: The Same Test, Both Ways
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
- Same steps, same underlying accessibility-tree referencing system (e12 means the same thing in both).
- The difference isn't what happens — it's where the resulting state lives and how much of it re-enters the model's context.
Step 4: Token Usage Comparison
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.
Step 5: Decision Table — Which One Should You Use?
| 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.
Conclusion
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!
Top comments (0)