Playwright CLI vs Playwright MCP: Which Should You Use with Claude Code?

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.

⚡ Update — 24th July 2026 (read this first)

Since I first published this, the numbers below shifted, and I want the post to stay honest — so here's the correction up front.

I re-ran the benchmark on the current Playwright MCP server (@playwright/mcp@0.0.78) against @playwright/cli@0.1.17. The ~4× token gap has essentially closed. Modern Playwright MCP no longer streams the full page state into the conversation on every call — like the CLI, it now writes the snapshot to disk and returns a short file path. On an identical login → dashboard flow the two tools landed within ~1% of each other, not 114k vs 27k.

The original numbers further down were a real measurement of older MCP behavior, so I've kept them for context and clearly marked them as historical. The full re-benchmark is in Step 4. Bottom line for 2026: choose between MCP and CLI based on filesystem access, not on token cost.

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

1. What Is Playwright MCP?
2. What Is Playwright CLI?
3. Step-by-Step: The Same Test, Both Ways
4. Token Usage Comparison
5. Decision Table: Which One Should You Use?
6. 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.
• In older versions, the full accessibility tree (and often screenshots) was returned as part of the tool result — injected straight into the model's context on every call. That's no longer the case: current MCP writes the snapshot to disk and returns a file path instead (see the Step 4 update).
• 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 (via the CLI's find command), 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(target="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 open https://demo.playwright.dev/todomvc
playwright-cli snapshot
playwright-cli fill e12 "Write blog post" --submit
playwright-cli snapshot

• Same steps, same underlying accessibility-tree referencing system (e12 means the same thing in both — they share the same playwright-core tooling).
• 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

Updated 24th July 2026 — read this before the original numbers below.

When I first wrote this, Playwright MCP returned the full accessibility tree inline on every tool call, which is where the eye-watering numbers came from. The current MCP server (@playwright/mcp@0.0.78) doesn't do that anymore — it writes the snapshot to disk and returns a file path, exactly like the CLI. I re-benchmarked both on an identical login → dashboard flow (navigate → snapshot → type username → type password → click → snapshot → screenshot):

Tool (current versions)	Chars returned into context, same 7-step flow
Playwright MCP 0.0.78	~3,580
Playwright CLI 0.1.17	~3,620

Within ~1% of each other, step for step. The clearest proof is a single navigate on a heavy 300-row page: both tools return only a ~230-character path to an on-disk snapshot, even though the full accessibility tree for that page is ~97,000 characters. That heavy tree only enters context if the agent explicitly asks for a full snapshot — and the token-efficient path (a scoped find) pulls ~450 characters in either tool.

The one real difference left is fixed startup overhead: MCP keeps its ~24 tool definitions (~18k characters) in the session's tool list the whole time, while the CLI reads a skill file once (~12.6k characters) and is otherwise just shell commands. So the honest 2026 takeaway is: pick based on whether your agent has filesystem access, not on per-action token cost.

Original benchmark (historical — reflects older MCP versions):

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 was close to a 90,000-token difference for the same task — because at the time MCP re-sent full page state into the conversation on every single tool call, while CLI kept that state on disk and Claude only pulled in the specific slice it needed. That exact mechanism is what changed: modern MCP now keeps state on disk too, which is why the re-benchmark above comes out roughly even.

For a one-off exploratory test, this difference barely mattered even then. Today, for a full regression suite the two are comparable per action — so the deciding factor is your environment and workflow, covered in the decision table below.

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 want the lightest fixed footprint and shell-native automation you can also run in CI
You want conversational back-and-forth over page structure	You want repeatable automation that composes with other shell/file steps

In practice, most teams don't pick just one — they keep CLI as the default for test writing and CI, and leave MCP configured as a fallback for quick interactive debugging or sandboxed clients where a shell isn't available.

Conclusion

Playwright MCP and Playwright CLI aren't competitors so much as tools for different moments — MCP for sandboxed, conversational exploration, and CLI for shell-native, CI-friendly automation. The big token gap that used to separate them has largely closed now that MCP keeps page state on disk, so in 2026 the choice comes down to environment and workflow rather than raw token cost. 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!