Playwright MCP server: tools, cost and trade-offs

What an AI agent can drive through Playwright, what the browser tools cost your context window, and why Microsoft's own README points coding agents at its CLI instead.

Last verified 1 September 2026 · from Microsoft's repository, its documentation and the server's own tools/list response

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector that lets the agent query the tool directly.

What is the Playwright MCP server?

It is Microsoft's server for the Model Context Protocol. The agent gains tools for driving a real browser: navigate, click, fill a form, take a snapshot, assert that text is visible.

It drives the browser through Playwright's accessibility tree rather than screenshots, so the agent reads structured page state instead of pixels. That is what makes the page readable by a text model. It is also what makes the output large.

There are two ways to automate a browser from an agent, and Microsoft documents both. This server is the MCP route. Playwright CLI with Skills is the other, and the README suggests it for coding agents.

Playwright covers code, tests and review broadly through browser testing, and reaches nothing in release, production observability, agent observability or cost.

In practice, Playwright answers questions you can only answer by using the product. An agent connected here can reproduce a bug, fill a form and confirm what a user sees. It cannot tell you whether the same flow is failing for real users, so pair this connector with an observability connector rather than replacing one.

What can an AI agent do with Playwright?

The pattern across these rows is that a session's cost is dominated by what the tools return, not by how many tools exist. A snapshot of a complex page is far larger than the 24 tool definitions that make it available.

What connecting costs before the first question

A context window is the amount of text a model can hold at once, and connecting uses some of it before the agent asks anything. Every tool the server registers sends its name, description and input schema to the model when the session starts. The tool list is charged whether or not a single tool is called.

Playwright keeps its descriptions short for a list of its size, at 68 characters per tool. That is deliberate, and it is not where the cost lives: the schemas are.

The README makes the cost argument itself. It steers coding agents to Playwright CLI with Skills because CLI calls avoid loading large tool schemas and verbose accessibility trees into the model context. The first half of that is the table below. The second half is every snapshot the agent takes afterwards.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 21 August 2026 from tools/list on the published @playwright/mcp package, run locally.

Registration is static, so no browser session was involved. Figures cover name, description and input schema. They do not include what tools return at run time. The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting, about 47%. Reasoning tokens are output, spent per request. The tool list is input, charged once at connection.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer, so the definitions were sent to the API's count_tokens endpoint and a no-tools baseline subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end, Opus 5 and Sonnet 5 at the high end. The gap between them is about a quarter.

Playwright MCP server limits: where answers come back incomplete

The limits below are about session cost, not about the connector failing.

How to configure Playwright MCP for agents

1. 1

   Decide whether the agent may execute code

   browser_run_code_unsafe is in the default set and its own description calls it RCE-equivalent. There is no read-only flag, so the only gate is your client's allowlist.

2. 2

   Choose a profile mode

   The default is a persistent profile holding your logged-in state, at a documented path per operating system. --isolated keeps the profile in memory instead, optionally seeded from --storage-state.

3. 3

   Run one client per profile

   A persistent profile can only be used by one browser instance at a time, so parallel clients sharing a workspace conflict. Give each additional client --isolated or its own --user-data-dir.

4. 4

   Do not treat --allowed-origins as a boundary

   The documentation is explicit that it is not a security boundary and does not affect redirects.

Paste this into your agent’s instructions

This connector's failure mode is cost rather than silence: snapshots are large and accumulate. The block makes the agent say what it looked at and why, so a session that spends its window on repeated snapshots is visible in the answer.

When you answer using Playwright MCP tools, state:
- What you looked at, and how. Prefer browser_find over a full
  browser_snapshot, and say which you used.
- The URL and the page state each observation came from.
- Whether a screenshot was saved. You receive a file path, not
  an image, so you cannot read it back.
Never state that data does not exist. State that it was not
found on the page under the constraints above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Not always, and Microsoft says so itself. The README suggests that coding agents may be better served by Playwright CLI with Skills than by this server.

The argument is token efficiency. CLI invocations avoid loading large tool schemas and verbose accessibility trees, so an agent working across a codebase keeps more of its window.

The server still wins where the work is interactive and exploratory, because a CLI call cannot hold a browser open across turns. For running an existing suite, or for a repeatable flow, the CLI is the better shape.

Use the CLI with Skills for a coding agent working in a repository. Use the server when the agent needs to explore a live page across several turns.

Playwright MCP server setup

There is nothing to install beyond Node: npx @playwright/mcp@latest fetches and runs the server. Browsers are downloaded on first use.

No credentials are involved. The server drives a browser on your machine, so the sensitive input is the profile it uses rather than an API key.

claude mcp add-json "playwright" '{"command":"npx",
  "args":["@playwright/mcp@latest","--isolated"]}'

{"mcpServers":{"playwright":{"command":"npx",
  "args":["@playwright/mcp@latest"]}}}

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest", "--isolated"]

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"playwright":{"command":"npx",
  "args":["@playwright/mcp@latest"]}}}

{"mcpServers":{"playwright":{"command":"npx",
  "args":["@playwright/mcp@latest"]}}}

{"servers":{"playwright":{"command":"npx",
  "args":["@playwright/mcp@latest"]}}}

{"mcpServers":{"playwright":{"command":"npx",
  "args":["@playwright/mcp@latest"]}}}

docker run -i --rm --init mcr.microsoft.com/playwright/mcp

npx @playwright/mcp@latest --headless --isolated \
  --storage-state ./auth.json

Read-only access, permissions and security

• One default tool is RCE-equivalent

  browser_run_code_unsafe executes arbitrary JavaScript in the Playwright server process, which is your machine. The description is Microsoft's own. Keep it off the allowlist.

• The server marks only 7 of 24 tools read-only

  The remaining 17 carry no readOnlyHint. That is accurate: clicking, typing and navigating all change state somewhere.

• The default profile is your logged-in state

  A persistent profile stores session cookies at a documented path. An agent driving that profile is acting as you, on whatever you are signed into.

• --allowed-origins is not a boundary

  The documentation states plainly that it does not serve as a security boundary and does not affect redirects.

Troubleshooting

The browser will not start, or two clients conflict

A persistent profile can only be used by one browser instance at a time. Start additional clients with --isolated, or give each its own --user-data-dir.

The agent burns its context after a few clicks

browser_snapshot returns the full accessibility tree each time. Use browser_find, which returns matching nodes with a few lines of context instead.

The agent cannot read the screenshot it took

Screenshots are written to the output directory and the agent receives a path. Use the accessibility tree for the agent's own reasoning and the screenshot for a human.

A documented tool is missing

Some tools sit behind --caps, which accepts vision, pdf and devtools. The default set is 24 tools; the documented set is larger.

The browser is still running after the task

The session holds a real browser process between calls by design. Call browser_close, or run the server in a container.

Playwright MCP server: Reference

What engineers report

Playwright's MCP server is among the most starred in the ecosystem, so the useful signals are its own guidance and its tool economy.

“When using the browser_take_screenshot tool in Playwright MCP v0.0.47, the returned screenshot data causes a permanent conversation-breaking error in Claude Code.”

“Every time the AI calls playwright MCP, it always prompts a browser instance conflict problem. How should this problem be solved? Otherwise, this MCP cannot be used normally.”

Repository facts from the GitHub API, retrieved 21 August 2026. Tool counts and description lengths come from the server's own tools/list response on the published npm package.

Should you connect an agent to Playwright?

Yes. Best for interactive browser investigation. For a coding agent running tests in a repository, take Microsoft's advice and use the CLI.

Strongest fit

Agents doing exploratory browser work across several turns: reproducing a bug, walking a signup flow, checking what a user actually sees.

Main advantage

A real browser driven through structured page state, with unusually terse tool descriptions for its size.

Main weakness

Session cost. What the tools return dwarfs what they cost to register, and snapshots accumulate.

Operational risk

The browser process persists between calls and does not close on its own.

Frequently asked questions