# Playwright MCP vs Playwright CLI: Browser Testing for Coding Agents

URL: https://developertoolkit.ai/en/ecosystem/mcp/playwright-mcp/
Description: Choose between Playwright MCP and Playwright CLI with its skill, set --isolated for parallel agents, and turn a bug report into a red-then-green E2E test in CI.

Playwright MCP (`@playwright/mcp`) and Playwright CLI (`@playwright/cli`) are Microsoft's two ways to let a coding agent drive a real browser through Playwright's accessibility snapshots. The MCP server keeps a live browser and returns page state inside every tool result. The CLI with its skill costs less context, and Microsoft's README points coding agents to it.

You ask the agent to fix a broken **Subscribe** button. It edits the click handler, runs the unit tests, and reports success, and nobody opened a browser. Or it did open one, and three agents in three worktrees fought over the same browser profile until two of them failed with a locked-profile error.

This page is for developers who want the agent to check its own UI work in a real browser, and for tech leads who need that to work with several agents running at once.

## What you get from this page

- A decision rule for Playwright MCP or Playwright CLI plus its skill, based on measured context cost.
- Install commands for Claude Code, Codex and Cursor, with the agent flags `--isolated`, `--headless` and `--caps`.
- A bug-report-to-regression-test workflow with its CI gate: the test fails first, the fix makes it pass, and CI keeps it.

## Should your agent use Playwright MCP or Playwright CLI?

Both packages drive the same Playwright engine and use the same element references from the accessibility snapshot. They differ in where the page data goes.

- **Playwright MCP** is a stdio MCP server. Each action (`browser_click`, `browser_navigate`) returns the resulting page snapshot inside the tool result, so the page lands in the model's context after every step.
- **Playwright CLI** is a shell command, `playwright-cli`. It writes the snapshot to a YAML file under `.playwright-cli/` and prints a link to it. The agent reads the file only when it needs to.

The Playwright MCP README (0.0.82, read 2026-09-26) states the choice outright: "If you are using a **coding agent**, you might benefit from using the CLI+SKILLS instead." Its reason is that CLI calls "avoid loading large tool schemas and verbose accessibility trees into the model context." It keeps MCP for "exploratory automation, self-healing tests, or long-running autonomous workflows where maintaining continuous browser context outweighs token cost concerns."

| | Playwright MCP | Playwright CLI + skill |
| --- | --- | --- |
| Package (npm, 2026-09-26) | `@playwright/mcp` 0.0.82 | `@playwright/cli` 0.1.21, binary `playwright-cli` |
| How the agent calls it | MCP tools (`browser_navigate`, `browser_snapshot`, …) | Shell commands (`playwright-cli goto`, `playwright-cli snapshot`, …) |
| Page state after each action | Inline in the tool result | Written to a file; the agent reads it on demand |
| Browser profile by default | Persistent, on disk, one per workspace | In memory; `--persistent` saves it |
| Works in | Any MCP client | Any agent that can run shell commands; the skill needs an agent that loads skills |
| Best for | Exploratory sessions, a human watching a headed browser, clients without a shell | Coding agents in a repository: test writing, verification, parallel sessions |

The decision rule: **default to the CLI plus skill in a repository where the agent can run shell commands.** Keep the MCP server when the agent has no shell, when you explore an unfamiliar app interactively, or when the team already manages MCP servers centrally and the context budget is not the constraint.

## Install Playwright MCP in Claude Code, Codex and Cursor

The server needs Node.js 18 or newer. Add `--isolated` from the start if more than one agent can run in the same checkout; the section on parallel agents explains why.

**Claude Code**

Project scope, so every clone and worktree gets the same entry (tested on Claude Code 2.1.283):

```bash
claude mcp add --scope project playwright -- npx @playwright/mcp@0.0.82 --isolated --headless
```

That writes this entry to `.mcp.json`, which you commit:

```json
{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@0.0.82", "--isolated", "--headless"],
      "env": {}
    }
  }
}
```

The `--` matters: without it, `claude mcp add` tries to parse `--isolated` as its own option. The README's shorter line, `claude mcp add playwright npx @playwright/mcp@latest`, works when you pass no server flags.

Alternatively, install the plugin from Anthropic's official marketplace. Its `.mcp.json` runs `npx @playwright/mcp@latest` with no flags, so it uses the persistent profile:

```bash
claude plugin install playwright@claude-plugins-official
```

**Codex**

Tested on codex-cli 0.157.1:

```bash
codex mcp add playwright -- npx @playwright/mcp@0.0.82 --isolated --headless
```

That writes a global entry to `~/.codex/config.toml`:

```toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@0.0.82", "--isolated", "--headless"]
```

Because the entry is global, it applies to every Codex session on the machine, including sessions started with `codex --worktree`. That is a reason to put `--isolated` in it rather than leaving it out. The README's own line is `codex mcp add playwright npx "@playwright/mcp@latest"`.

**Cursor**

Add the server in **Cursor Settings > MCP > Add new MCP Server** as a `command` type with `npx @playwright/mcp@latest`, or put the standard configuration in `.cursor/mcp.json` (shape from the Playwright MCP README; not tested in a Cursor binary):

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@0.0.82", "--isolated", "--headless"]
    }
  }
}
```

Confirm it loaded: run `/mcp` in Claude Code or Codex, or `codex mcp list` in a terminal, and check that `playwright` is connected. In Cursor, open the MCP list in settings.

**Pin the version in shared configuration**

The entries above pin `@playwright/mcp@0.0.82`, including the machine-wide Codex entry. `@latest`, as in the README's own lines, pulls whatever Microsoft published last into every session and every CI run. In any shared configuration, pin a version you have tested and bump it on purpose.

## Install Playwright CLI and its skill

Install the CLI once per machine, then install the skill into each repository so it travels with the code (tested with `@playwright/cli` 0.1.21):

```bash
npm install -g @playwright/cli@latest
playwright-cli --help
```

**Claude Code**

```bash
playwright-cli install --skills
```

The default target is `claude`: the command writes `.claude/skills/playwright-cli/SKILL.md` plus a `references/` folder with guides for test generation, running tests, request mocking, storage state and tracing. Commit the folder. Add `--global` to install into your home directory instead.

**Codex**

```bash
playwright-cli install --skills agents
```

This writes the same skill to `.agents/skills/playwright-cli/`, the repository folder Codex scans for shared skills (see [Codex team workflows](/en/codex/team/team-workflows/)). Run `/skills` in a Codex session to confirm it is listed.

**Cursor**

```bash
playwright-cli install --skills agents
```

This writes the skill to `.agents/skills/playwright-cli/`. Cursor's skill folders could not be checked against cursor.com on 2026-09-26, so confirm in Cursor that the skill appears. If it does not, use the README's skills-less route: tell the agent to run `playwright-cli --help` and work from the command list.

The skill's frontmatter pre-approves `Bash(playwright-cli:*)`, `Bash(npx:*)` and `Bash(npm:*)` in agents that honour `allowed-tools`. Read that line before you commit the skill: `npx:*` and `npm:*` are broader than browser testing needs.

**Install traps**

- `npm i -g playwright-cli` installs a **deprecated** unscoped package (npm: "This package is deprecated, use @playwright/cli instead."). The binary of the correct package is still called `playwright-cli`.
- `@microsoft/playwright-mcp` does not exist on npm (404). The unscoped `playwright-mcp` package exists and is not Microsoft's. The server is `@playwright/mcp`.
- `playwright-mcp --help` in 0.0.82 lists `vision`, `pdf` and `devtools` for `--caps`. The README also documents `testing`, `network`, `storage` and `config`, and the server accepts them. Do not conclude from `--help` that test assertions are unavailable.
- Add `.playwright-cli/` to `.gitignore`. The CLI writes snapshots there after every command.

## Flags that matter when an agent drives Playwright MCP

All flags below are from `playwright-mcp --help` and the README, version 0.0.82. Each also has an environment variable, such as `PLAYWRIGHT_MCP_ISOLATED`.

| Flag | What it does | When to set it |
| --- | --- | --- |
| `--isolated` | Keeps the browser profile in memory and does not save it to disk | Always when more than one agent can run; always in CI |
| `--headless` | Runs without a visible window (headed is the default) | Background agents, CI, remote containers |
| `--caps testing` | Adds `browser_generate_locator` and the `browser_verify_*` assertion tools | When the agent writes tests from what it sees |
| `--caps network` | Adds `browser_route`, `browser_unroute` and `browser_network_state_set` for mocking and offline mode | Reproducing a bug that depends on an API response |
| `--caps vision,pdf,devtools` | Coordinate-based mouse tools, PDF export, tracing and video | Canvas-heavy UIs, PDF output, trace capture |
| `--storage-state <path>` | Loads cookies and local storage into an isolated context | Testing behind a login without a persistent profile |
| `--user-data-dir <path>` | Uses a specific persistent profile directory | When you need a persistent profile per agent |
| `--console-level error` | Returns only console messages at that level and above | Keeping console output short |
| `--output-dir <path>` | Where automatically named screenshots and files go | Collecting evidence for the pull request |

## Check a page: open pricing, click Subscribe, report errors

Run this first: it answers what a unit test cannot, whether the page works in a browser. Start your dev server first. The prompt works in all three tools.

**Copy-paste prompt: pricing page smoke check**

```text
The dev server is running at http://localhost:4321. Using Playwright, open /en/pricing, take an accessibility snapshot, and click the button whose accessible name contains "Subscribe". Wait for navigation or a network response to finish. Then report: (1) every console message at error level, with its source; (2) every network request with a status of 400 or above, or that failed, with method, URL and status; (3) the URL you ended on. Save a screenshot as evidence/pricing-subscribe.png. Do not change any code.
```

What you should see with **Playwright MCP**: `browser_navigate`, `browser_snapshot`, `browser_click` (with an element reference from the snapshot, such as `e21`), then `browser_console_messages` with `level: "error"`, `browser_network_requests`, and `browser_take_screenshot`. `browser_network_requests` leaves out successful static resources by default, which keeps the list short.

What you should see with **Playwright CLI**: the same steps as shell commands.

```bash
playwright-cli open http://localhost:4321/en/pricing
playwright-cli snapshot
playwright-cli click e21
playwright-cli console error
playwright-cli requests
playwright-cli screenshot
```

If the agent reports "no errors" without having called the console and network tools, it guessed. Ask it to show the tool output.

## Turn a bug report into a regression test with Playwright

The smoke check proves the page works today. A test proves it keeps working. The workflow below is the one to standardise on: the agent reproduces the bug in a browser, writes a Playwright test that fails for the right reason, fixes the code, and proves the same test passes. It uses `@playwright/test` (1.63.0 on npm, 2026-09-26) as the runner, whichever driver the agent explores with.

1. **Give the agent the bug report and forbid the fix.** The first deliverable is a failing test, not a patch.

   **Copy-paste prompt: reproduce and write the failing test**

   ```text
   Bug report: "On /en/pricing, clicking Subscribe on the annual plan does nothing. Console shows TypeError: Cannot read properties of undefined (reading 'priceId')."
   Reproduce it with Playwright against http://localhost:4321. Then write tests/e2e/pricing-subscribe.spec.ts with @playwright/test that clicks Subscribe on the annual plan and asserts that the checkout request is sent and that no console error is logged. Use role-based locators (getByRole) taken from the snapshot, not CSS selectors. Run only this test with: npx playwright test tests/e2e/pricing-subscribe.spec.ts --retries=0 --trace=on
   Show me the failure output and stop. Do NOT commit, and do NOT change any application code yet.
   ```

2. **Check that it fails for the right reason.** The failure must be the bug from the report (the missing checkout request or the `TypeError`), not a timeout on a wrong locator or a server that was not running. A test that fails for the wrong reason proves nothing when it later passes. Once it fails for the right reason, commit the test alone (`test: reproduce pricing subscribe bug`), so the red state has its own commit.

3. **Let the agent fix the code, not the test.**

   **Copy-paste prompt: fix until green, test untouched**

   ```text
   The failure in tests/e2e/pricing-subscribe.spec.ts reproduces the bug. Fix the application code so the test passes. Do not edit the test file; if you believe the test is wrong, stop and explain why. After the fix, run the test with --repeat-each=5 --retries=0 and run the full E2E suite once. Report the pass counts and attach the trace path for one passing run.
   ```

   `--repeat-each=5` runs the test five times. A test that passes four times out of five is a flaky test, not a fix.

4. **Keep the test in CI.** The pull request holds two commits: the red test, then the fix. The CI job runs the E2E suite with `--fail-on-flaky-tests`, so a test that only passes on retry fails the build, and it checks that the spec did not change after the red commit:

   ```yaml
   # .github/workflows/e2e.yml (job steps; checkout needs fetch-depth: 0)
   - run: npx playwright install --with-deps chromium
   # --retries=2 lets Playwright detect a flaky test; --fail-on-flaky-tests fails the build on one
   - run: npx playwright test --retries=2 --fail-on-flaky-tests
   - name: Spec unchanged since the red commit
     run: |
       RED_SHA=$(git log --format=%H --grep='^test: reproduce pricing subscribe bug' -n 1)
       git diff --exit-code "$RED_SHA" HEAD -- tests/e2e/pricing-subscribe.spec.ts
   ```

   The diff step fails the build if the fix commit touched the test.

5. **Attach the evidence.** The pull request carries the red run output from step 1, the green runs from step 3, the trace, and the screenshot. The [evidence bundle](/en/workflows/ship/evidence-bundle/) page has the template that makes these fields required.

With Playwright CLI, the skill adds a shortcut to step 1: each `playwright-cli` action prints the equivalent Playwright TypeScript (`await page.getByRole('button', { name: 'Subscribe' }).click();`), so the agent assembles the test from the actions it already took. The skill's `references/test-generation.md` calls this plan, generate and heal. With Playwright MCP, `--caps testing` gives the agent `browser_generate_locator` for the same purpose.

## Run one agent per worktree without browser collisions

The Playwright MCP README is explicit: "A persistent profile can only be used by one browser instance at a time, so concurrent MCP clients sharing the same workspace will conflict." The fix it gives is to start each additional client with `--isolated` or with a distinct `--user-data-dir`.

The default profile path ends in `{workspace-hash}`, derived from the client's workspace root, so two worktrees usually get separate profiles already. Two agents in the **same** checkout do not, and the hash depends on what the client reports as its root. `--isolated` removes the question: every session starts from a clean in-memory profile, which is also what a test should start from.

Browser profiles are only half of it. The other shared resource is the dev server port:

| Shared resource | What goes wrong | Setting that prevents it |
| --- | --- | --- |
| Playwright MCP profile | Second browser fails to start, or reuses another agent's login | `--isolated` in the committed MCP entry |
| Playwright CLI session | Two agents drive the same named browser | Start each agent with its own `PLAYWRIGHT_CLI_SESSION`, or prepend `-s=<name>` to each command |
| Dev-server port | Astro, Vite and Next.js move to the next free port without failing; the agent tests another worktree's server | A fixed port block per worktree |
| `reuseExistingServer` in `playwright.config.ts` | Playwright attaches to whatever already listens on the port and reports green against code that was never under test | Derive `baseURL`, `webServer.url` and the dev-server port from one per-worktree value |

For Playwright CLI, the README's pattern is an environment variable at agent start. In a worktree, name the session after the directory:

```bash
PLAYWRIGHT_CLI_SESSION="$(basename "$PWD")" claude
```

Run `playwright-cli list` to see every open session, and `playwright-cli show` to open a dashboard with a live view of each one. For the full worktree setup, including port blocks, see [running many agents at once](/en/ecosystem/agent-tools/parallel-agents/).

**Copy-paste prompt: worktree-safe browser check**

```text
You are running in a git worktree next to other agents. Before any browser work: read the dev-server port for this worktree from its environment file (for example .wt-env) or from the dev server's own startup output, and use only that port. Confirm with curl that the server on that port serves this worktree by checking a string you changed in this branch. Use Playwright with an isolated profile. If the port is taken or the string is missing, stop and tell me instead of testing another server.
```

## How to prove the browser check means something

A browser check makes the agent's claim observable. It proves the change only when the check could have failed and is kept where the agent cannot quietly weaken it.

| Check | What it proves | Who owns it |
| --- | --- | --- |
| Red run before the fix, with the failure message | The test detects this bug | Author (agent); the reviewer reads the message |
| Green runs with `--repeat-each=5 --retries=0` | The fix works and the test is not flaky | Author (agent); CI reruns it |
| Test file unchanged between the red and green commits | The agent fixed the code, not the test | CI diff check; see [protecting the oracle](/en/workflows/test/protect-the-oracle/) |
| E2E suite in CI with `--fail-on-flaky-tests` or zero retries | The behaviour stays fixed on every later change | CI, blocking |
| Trace and screenshot attached to the pull request | A reviewer can replay what the browser did without rerunning it | Author (agent) |

The tech lead approves on that evidence. For the reviewing side of the loop, see [reviewing an agent's pull request](/en/workflows/ship/agent-pr-review/).

**Copy-paste prompt: self-check before the pull request**

```text
Before opening the PR: (1) check out the commit that holds only the test (the one before your fix commit), run tests/e2e/pricing-subscribe.spec.ts, and confirm it fails with the original bug; (2) return to HEAD and run it with --repeat-each=5 --retries=0; (3) confirm with git diff that the spec did not change between the two runs; (4) list the trace and screenshot paths. Put all four results in the PR description under "Browser evidence".
```

## What Playwright MCP and Playwright CLI cost in context

Measured on 2026-09-26 by listing the tools of `@playwright/mcp` 0.0.82 over stdio:

| Configuration | Tools | Tool-schema JSON |
| --- | --- | --- |
| Default | 25 | about 20,100 characters |
| `--caps testing,network` | 34 | about 25,700 characters |
| All seven capability groups | 72 | about 45,400 characters |
| Playwright CLI skill | 0 (shell commands) | the `SKILL.md` body is 15,179 characters, loaded when the skill triggers |

The schemas are the smaller cost. Claude Code 2.1.283 and codex-cli 0.157.1 both load MCP tool schemas on demand through tool search. The larger cost is the accessibility snapshot that Playwright MCP returns after every action: it grows with the size of the page and repeats with every click, so a ten-step flow on a content-heavy page pays for ten snapshots.

Ways to cut it, cheapest first:

- Use Playwright CLI, which writes snapshots to files.
- On Playwright MCP, ask for `browser_snapshot` with `depth` or a `target` element, or with `filename` to save it instead of returning it.
- Start the server with `--snapshot-mode none` when the agent drives a known flow and does not need the page after each step.
- Add only the `--caps` groups the task needs.
- Push long browser sessions into a subagent so only its summary returns to the main session.

To measure it yourself in Claude Code, run `/context` before and after the pricing-page check, once with each driver. For the general pattern, see [reducing MCP token cost](/en/ecosystem/mcp/reducing-mcp-token-cost/).

## How popular are Playwright MCP and Playwright CLI?

As of 2026-09-26: `microsoft/playwright-mcp` has 37.6k GitHub stars and is listed in the Official MCP Registry as `io.github.microsoft/playwright-mcp` 0.0.82; the `playwright` plugin has 319,887 installs on the Claude plugin directory (`claude.com/plugins`). `microsoft/playwright-cli` has 13.6k GitHub stars, and its skill shows 165,672 all-time installs in a third-party scrape of skills.sh (`LinklyAI/best-skills`, dated 2026-09-26; secondary, because skills.sh itself could not be read).

## When Playwright MCP or Playwright CLI breaks

**The browser fails to launch or reports a locked profile.** Another agent or an earlier session holds the persistent profile. Recovery: add `--isolated` to the MCP entry, or give each agent its own `--user-data-dir`. For a stuck CLI session, run `playwright-cli list`, then `playwright-cli close-all`, and `playwright-cli kill-all` if processes remain.

**No browser is installed.** A fresh machine or CI container has no browser binaries, and the first navigation fails. Recovery: run `npx playwright install chromium` (add `--with-deps` on Linux CI images), or `playwright-cli install-browser` for the CLI. Choose a channel explicitly with `--browser chrome|firefox|webkit|msedge`.

**The test passed against the wrong server.** The dev server moved to the next free port, and the agent or `reuseExistingServer` hit another worktree's server. Recovery: pin a port per worktree, derive `baseURL` and `webServer.url` from it, and ask the agent to prove which server it tested, as the worktree prompt does.

**The agent edits the test until it passes.** The red run was real; the green run came from a weaker assertion. Recovery: make "test file unchanged" a CI check, and put `tests/e2e/` under a deny rule or `CODEOWNERS` as described in [protecting the oracle](/en/workflows/test/protect-the-oracle/).

**The test is flaky.** It passes locally and fails in CI, often on a fixed `waitForTimeout` or a CSS selector. Recovery: rerun with `--repeat-each=10 --retries=0` and `--trace=on`, open the trace, and ask the agent to replace sleeps with web-first assertions and CSS selectors with role-based locators.

**The login state is gone.** `--isolated` discards cookies when the browser closes. Recovery: save a storage state once with Playwright's setup project or `playwright-cli state-save auth.json`. On Playwright MCP, pass it with `--storage-state auth.json`; on Playwright CLI, run `playwright-cli state-load auth.json`. Keep that file out of Git; it holds session cookies.

**The context window fills after a few clicks.** Each MCP action returned a full snapshot of a large page. Recovery: switch that task to Playwright CLI, or use the snapshot limits in the previous section.

**What the browser can reach**

The default tools include `browser_run_code_unsafe` and `browser_evaluate`. The README describes the first as executing "arbitrary JavaScript in the Playwright server process" that "is RCE-equivalent". Page text is untrusted input: a page can carry instructions aimed at the agent. Point the agent only at your own app, keep production credentials out of storage-state files, and note that `--allowed-origins` and `--blocked-origins` are, in the README's words, not "a security boundary". Run agents that browse untrusted sites in a sandbox. See [securing MCP servers](/en/ecosystem/mcp/mcp-security/).

## Where to go next with browser testing for agents

- [Browser automation for agents](/en/ecosystem/mcp/browser-automation/) — Playwright against Chrome DevTools MCP, Browser Use and the other drivers, job by job.
- [agent-browser](/en/ecosystem/skills/agent-browser/) — Another CLI plus skill for checking the running app, with screenshots as evidence.
- [End-to-end test automation](/en/workflows/test/e2e-testing/) — Structure the E2E suite the agent adds to.
- [Protecting the oracle](/en/workflows/test/protect-the-oracle/) — Keep the agent from weakening the tests that judge it.
- [Running many agents at once](/en/ecosystem/agent-tools/parallel-agents/) — Worktrees, port blocks and the review queue.
- [Must-have MCP servers](/en/ecosystem/mcp/essential-servers/) — Where Playwright fits among the servers most teams install first.
