Playwright MCP vs a Playwright CLI wrapper for browsing agents

The playwright mcp vs cli decision is not about which integration has more features. Both use the same underlying Playwright API and drive the same Chromium engine. The difference is where state lives between browser actions. MCP (Model Context Protocol) routes every interaction as a structured tool call through a local server, keeping DOM snapshots and artefacts inside the LLM context window. The CLI exposes those same actions as shell commands and writes output to disk. That single mechanical distinction drives a 4x gap in token consumption, determines whether your sessions survive a context reset, and controls whether your browser automation agent produces auditable artefacts for debugging. Choose the wrong integration contract early and you'll refactor more than you expected.

What each integration mode actually does under the hood

Both modes wrap the same Playwright core library. Clarifying this upfront matters because the tooling names suggest a deeper split than actually exists.

In MCP mode, you install the @playwright/mcp package and start a local MCP server. When the LLM issues a tool call (navigate to this URL, click this element, extract this text), the server translates it into a Playwright API call, runs it in a managed browser instance, and returns the result as structured JSON. That JSON response, which can include DOM snapshots, screenshot base64 blobs, and accessibility trees, gets appended to the LLM context. The agent never touches the local filesystem directly.

The CLI mode wraps Playwright actions as shell commands. The agent executes a command, Playwright runs the corresponding browser operation, writes artefacts to the local filesystem (screenshots as files, session cookies in a directory, traces as .zip archives), and returns a compact text string to the shell. The LLM reads that brief confirmation, not the full artefact.

The playwright.dev documentation from Q4 2025, still current in 2026, frames this as a state location question: the context window versus the filesystem. That framing is the most useful lens for the rest of the comparison.

Playwright MCP vs CLI: the token cost gap in numbers

A benchmark published by test-lab.ai in February 2026 measured token consumption across matched browser interaction tasks. CLI mode averaged roughly 27,000 tokens per task. MCP mode consumed approximately four times that figure for the same set of interactions.

Why snapshots are the primary driver

When an MCP-based headless browser control loop needs to understand the current page state, it injects an accessibility tree or full DOM snapshot directly into the context. That snapshot commonly reaches 10,000 to 30,000 tokens for a moderately complex page. CLI mode writes the same snapshot to a file and returns a path string of a few dozen tokens.

The secondary cost is payload verbosity. MCP tool call responses are structured JSON with field names, nesting, and metadata overhead. Shell output from the CLI is compact: a status line, an exit code, a file path.

Cost at scale: a back-of-envelope for 1,000 tasks/day

At 2025 Claude Sonnet pricing (approximately $3 per million input tokens), the operational difference looks like this:

• CLI at 27,000 tokens x 1,000 tasks = 27M tokens/day, roughly $81/day
• MCP at 108,000 tokens x 1,000 tasks = 108M tokens/day, roughly $324/day

The multiplier holds at comparable GPT-4o pricing. At modest task volume the absolute dollar difference is manageable. At 10,000 tasks per day, you're looking at a $2,400/day gap from the integration choice alone.

State, persistence, and auditability across turns

This is where playwright mcp vs cli shows its sharpest practical difference for multi-turn agent runs.

CLI mode produces durable artefacts. Cookies and session data persist across turns in a directory on disk. If the context window resets between agent sessions, the browser session continues where it left off because state is stored outside the LLM. Playwright trace files (the .zip archives that record every network request, DOM snapshot, and screenshot in a replayable format) average 200 to 800 KB per session. They integrate cleanly with CI pipelines, can be attached to failing test runs, and can be inspected after the fact with the Playwright Trace Viewer.

MCP mode is ephemeral by default. All state lives in the context window. This is simpler to configure: no disk paths, no file permissions, no artefact management. But when the context resets, the session resets. And if you wanted those same 200-to-800 KB trace files inlined into the context rather than written to disk, you'd be adding 150,000 to 600,000 tokens per session. That erases the simplicity argument for any workload longer than a single short task.

For automated browser testing with reproducibility requirements, the CLI's on-disk artefacts are decisive. For a lightweight LLM web navigation tool running a single isolated task, the difference is minor. Honestly not sure why anyone would pick MCP for serious testing workloads when the token math is this brutal 💸

Which agent architecture fits each mode: a decision table

The official playwright.dev documentation (published 2025, current in 2026) maps agent type to integration mode. The table below consolidates that recommendation with the cost and state arguments above.

Agent type	Recommended mode	Primary reason
Coding agents (Claude Code, GitHub Copilot)	CLI	Shell access available; artefacts needed for debugging
Specialized agentic loops with persistent state	MCP	Context-native integration; no filesystem dependency
Sandboxed runtimes, no-shell environments	MCP	CLI execution not available
CI testing pipelines	CLI	Trace files and screenshots for failure triage
High-volume AI-driven browser tasks	CLI	4x token cost advantage at scale
Short single-task agent web scraping jobs	Either	Token gap negligible at low volume

One edge case fits neither mode cleanly: very long multi-step sessions with large DOM snapshots. MCP context grows without bound across turns. CLI reduces context cost but adds round-trips to read back summaries. The Skills API (see the next section) is the current mitigation. It wraps common multi-step patterns into single tool calls, reducing both context growth and round-trip count.

The single deciding question remains: can your agent runtime invoke a shell command? If yes, start with CLI. If not, MCP is the correct path.

Ecosystem status in 2026: Skills, MCP servers, and adoption signals

Microsoft ships both modes from the same repository. The @playwright/mcp package on npm has followed the Playwright core release cadence since its 1.0 launch, with consistent weekly download volume in the hundreds of thousands reflecting broader MCP ecosystem growth across AI tooling in 2025-2026.

The CLI path received a significant addition during this period: the Skills API. A Skill wraps a sequence of Playwright operations (navigate, interact, extract, assert) into a single named tool call. Where raw CLI invocation might require five separate shell calls to fill a form and verify a result, a Skill collapses them into one. This cuts round-trips and the token overhead of managing intermediate results, making the playwright mcp vs cli cost gap even larger in favour of CLI for complex multi-step tasks.

The 2025-to-2026 Playwright documentation cycle made CLI the explicit default recommendation for coding-agent integrations. The reasoning is direct: coding agents already have shell access, already expect file artefacts for debugging, and already run in environments where trace inspection is standard practice. MCP remains the recommended path for sandboxed or no-shell runtimes, and for any scenario where installing a CLI binary is not feasible. Though I suspect most developers will gravitate toward CLI once they see the token bills from MCP mode. C'est la vie.

For high-volume automated browser testing or agent web scraping workloads, the token cost argument continues to push serious deployments toward CLI. The 4x multiplier documented in the February 2026 benchmark isn't an edge case; it reflects the structural overhead of routing artefacts through the context window rather than writing them to disk.

Key takeaways

Filesystem access is the single deciding variable when choosing between playwright mcp vs cli. Reach for CLI when your agent runtime can invoke shell commands: you get 4x lower token costs, durable session artefacts, and native CI pipeline integration. Switch to MCP when the shell is unavailable, when you're building inside a sandboxed runtime, or when zero-configuration state management matters more than token efficiency. The Skills API narrows the ergonomic gap further in CLI's favor for complex multi-step tasks.

---

CLI writes browser snapshots to disk and costs 4x fewer tokens than MCP for the same task. The welcome kit includes a CLI blueprint showing how to structure Playwright commands as agent tools, with the exact patterns Phil uses in production.

→ Get the welcome kit