playwright MCP

Playwright MCP is Microsoft's server that lets an AI agent drive a real browser through the Model Context Protocol: it opens pages, clicks, fills forms and reads the result as structured text. In Claude Code you install it with claude mcp add playwright npx @playwright/mcp@latest. It is Apache-2.0, free, and needs Node.js 18 or newer. We checked the README and repo on 31 October 2026.

Quick facts

The release number is the one GitHub lists as "latest". The version string starts with 0.0, so treat the tool names and options as able to change between releases. Pin a version if you share a config with a team.

What it lets an agent do

A coding agent that edits front-end code cannot see the result. It can read the diff and guess. With Playwright MCP it can open the page, look at it, click through the flow and tell you what actually happened.

The server does this through accessibility snapshots. Instead of sending a screenshot to the model, it sends a text tree of the page: roles, names, states, and a reference for each element. The README lists three reasons for this design: it is fast and light, it needs no vision model, and it is deterministic because the agent points at a named element rather than at pixels.

In practice that covers jobs like these:

• Reproduce a bug from a URL and a set of steps.
• Walk a signup, checkout or settings flow and report where it breaks.
• Check a page at a phone width, then again in dark mode.
• Read the console and network log after a failed action.
• Upload a file, handle a dialog, drag an item across a list.
• Generate a Playwright locator or a test assertion for something it just verified.

Install it in each agent

The standard config works in most clients. It runs the package with npx, so there is nothing to install first.

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

Claude Code

The README gives this line:

claude mcp add playwright npx @playwright/mcp@latest

Claude Code's own docs describe the general form as claude mcp add [options] <name> -- <command> [args...], where the double dash separates Claude's options from the server's. If you want to pass options to Playwright MCP, use that form:

claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest --headless

Claude Code has three scopes. Local is the default and stays private to you in ~/.claude.json. Project scope writes a .mcp.json at the project root so teammates get the same server from version control, and Claude Code asks each person to approve it. User scope loads the server in every project. Add --scope project or --scope user to choose. Check what is connected with /mcp inside a session.

Cursor

The README offers an install button, or you can add it by hand under Cursor Settings, MCP, Add new MCP Server, using the command npx @playwright/mcp@latest. Cursor reads mcp.json, in .cursor/mcp.json for one project or ~/.cursor/mcp.json for all of them, and the entry has the same shape as the standard config above.

Codex

The README gives a CLI line and a config file alternative:

codex mcp add playwright npx "@playwright/mcp@latest"

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

That goes in ~/.codex/config.toml, or in .codex/config.toml to scope it to one project, per the Codex docs. Run codex mcp list to see what is configured, or /mcp inside the TUI.

Gemini CLI

The README says to use the standard config in your Gemini CLI settings.json under mcpServers. Gemini CLI also has gemini mcp add, which takes a name and a command, and supports a trust flag per server. Leave trust at false. When it is true, Gemini CLI skips the confirmation prompt for that server's tool calls, which you do not want on a browser.

VS Code

The README shows an install button and a command line version:

code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

VS Code's docs give a slightly different example that includes "type":"stdio". Use that one if the first form is rejected. Be careful with file formats: VS Code's .vscode/mcp.json uses a top-level servers key, while the portable file format uses mcpServers. Copying one into the other is a common reason a server does not appear.

Other clients

The README also covers Amp, Antigravity, Cline, Copilot CLI, Factory, Warp and Windsurf, mostly by pointing at the standard config.

Compatibility at a glance

The tools it exposes

The README groups tools by capability. The default set is core automation, tab management and browser installation. Everything else is opt-in.

Core automation (on by default):

The README describes browser_run_code_unsafe as running arbitrary JavaScript in the Playwright server process and being "RCE-equivalent". That is the README's wording, and it is a good reason to read tool calls before approving them.

Tab management: browser_tabs lists, opens, closes and selects tabs.

Opt-in groups. The README headings name them as config, network, storage, devtools, vision, pdf and testing. The --caps option row lists vision, pdf and devtools as its values, so check the README for the exact flag if you need network routing or storage tools. [VERIFY: whether --caps accepts config, network, storage and testing]

• Network: browser_route, browser_route_list, browser_unroute, browser_network_state_set.
• Storage: cookie, localStorage and sessionStorage get, set, list, delete and clear tools, plus browser_storage_state and browser_set_storage_state.
• DevTools: highlight and annotate, tracing, video and recording tools.
• Vision: coordinate-based mouse tools such as browser_mouse_click_xy.
• PDF: browser_pdf_save.
• Testing: browser_generate_locator and verify tools for visible element, visible list, visible text and value.

Every tool you expose costs context, because the schema is loaded into the model's window. Leave groups off until a task needs them.

Options worth knowing

You pass these as extra args in the config, or as PLAYWRIGHT_MCP_* environment variables. The README lists dozens; these are the ones we would reach for first.

Profiles, sessions and logins

This is where most setups go wrong, so it gets its own section.

By default the server uses a persistent profile. On macOS that is ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}, and the hash comes from the workspace root, so each project gets its own. Anything you log into stays there between sessions. That is handy for an internal site and risky for everything else.

Only one browser can use a persistent profile at a time. If two MCP clients share a workspace, they conflict. The README's fix is --isolated for the extra clients or a distinct --user-data-dir.

In isolated mode the profile lives in memory and the state is lost when the browser closes. You can seed it from a saved file with --storage-state, which loads cookies and local storage into the fresh context. That is the clean way to test a logged-in page without leaving a real session on disk.

The third route is the browser extension: --extension connects to a Chrome or Edge you already have open, with your logged-in tabs. It is convenient and it hands the agent your real sessions. Use it only on trusted pages.

Real tasks with copy-ready prompts

These prompts are starting points. Adjust the URL and the flow.

Check a change after an edit

I just changed the pricing page. Open http://localhost:4321/pricing,
take a snapshot, and tell me whether the three plan cards and the
FAQ render. Then resize to 390 by 844 and tell me if anything overflows.

Reproduce a bug

Open https://staging.example.com/login. Sign in with the test account
I will paste next. Go to Settings, change the display name, save, and
report the exact error text and any console errors or failed network
requests. Do not retry more than twice.

Dark mode and reduced motion

Open the homepage, emulate dark color scheme and reduced motion, take
a screenshot for each, and list any element whose text looks low
contrast in the snapshot.

Turn a manual check into a test

Walk through adding an item to the cart on /shop. Once it works, write
a Playwright test in TypeScript that repeats those steps, using
getByRole locators where you can.

Find what a page loads

Load /dashboard, then list the network requests that returned 4xx or
5xx and show the response body for the first one.

For a fuller recipe that wires this into a review loop, see the browser QA recipe.

Security and permissions

Read this part before you point the server at anything you care about.

It is not a sandbox. The README says so in one line: Playwright MCP is not a security boundary. It points to the MCP security best practices page.

The browser carries your sessions. With the default persistent profile or the extension, every site you are logged into is reachable by the agent. A page the agent visits can contain instructions aimed at the model, which is called prompt injection. Claude Code's MCP docs warn that servers which fetch external content can expose you to this, and a browser is the clearest example.

File access is limited by default. The README says file system access is restricted to workspace roots, and navigation to file:// URLs is blocked. The flag --allow-unrestricted-file-access turns that off. Leave it off.

Origin filters are a convenience. --allowed-origins and --blocked-origins are described as not a security boundary, and they do not affect redirects. Do not rely on them to keep an agent off a site.

Binding. The HTTP mode binds to localhost by default. The README notes --host 0.0.0.0 binds to all interfaces. Do not do that on a shared network without a proxy and authentication in front.

A sensible baseline:

1. Use --isolated for anything public or untrusted.
2. Keep logged-in profiles for trusted internal sites only.
3. Do not set a Gemini trust flag or an auto-approve mode for this server.
4. Read browser_evaluate and browser_run_code_unsafe calls before you approve them.
5. Never paste real production credentials into a prompt. The --secrets option reads a dotenv file instead.

Limits and known issues

• Token cost. Snapshots and tool schemas take context. The README itself says coding agents often do better with the Playwright CLI plus skills, because CLI calls avoid loading large schemas and long accessibility trees. It keeps MCP for exploratory automation, self-healing tests and long-running loops. That is a fair steer from the maintainers.
• Docker is narrower. The README notes the Docker image supports headless Chromium only.
• One profile, one browser. Parallel clients need --isolated or separate data directories.
• Open reports. At the time we checked, the issue list held items such as a request to bound settle waits on pages whose timers cannot run (#43752 and a fix proposal in #43767), a report that the snapshot includes off-screen elements (#39955), and a Docker image request about a certificate update (#1808). Check the tracker for your version before you rely on a behavior.
• Pre-1.0 versioning. The latest tag is v0.0.83, so options can be renamed. The README mentions flags such as --mobile and --no-webmcp that are newer than many blog posts you will find.

Alternatives

Pair it with Context7 MCP for current framework docs, or with GitHub MCP to file the bug you just reproduced. The full MCP servers hub lists the rest.

Which agents it works best with

Any client that speaks MCP can run it. The practical difference is how each one handles approval and context.

• Claude Code is the easiest fit for a front-end loop: edit, open the page, check, edit again. Project scope lets a team share one config.
• Cursor and VS Code suit people who want the browser result next to the editor. Mind the different JSON keys.
• Codex takes a TOML entry, and its docs describe a per-server tool allow list, which helps you leave the risky tools out.
• Gemini CLI works with the standard config and has includeTools and excludeTools filters for the same purpose.

Our take

We did not run a benchmark for this page, so this is a read of the documentation, not a test result.

The design choice that matters is the accessibility snapshot. It makes the server cheap to reason about for the model and easy to audit for you, because a tool call names an element rather than a coordinate. For checking front-end work it is the most direct way we know of to give an agent eyes.

The honest caveat comes from the README itself. The maintainers say coding agents often get more value from the CLI with skills, and that MCP earns its place when the loop is long and needs state. If your agent mostly does short checks, try the CLI first. If it explores a site, or you want a human-readable record of each step, the MCP server is the better pick.

Treat the profile as the real decision. Isolated for the public web, persistent for internal tools you trust, and the extension only when you must reuse a live login. Most of the risk in this server comes from that choice, not from the code.

A short setup checklist

1. Confirm node --version prints 18 or newer.
2. Add the server with the line for your agent above.
3. Start a fresh session and list tools (/mcp in Claude Code and Codex).
4. Ask for a snapshot of a local page before anything else.
5. Add --headless and --isolated once the first run works.
6. Turn on one opt-in group at a time, only when a task needs it.
7. Pin the package version if the config is shared.

Frequently asked questions

What does Playwright MCP need to run? Node.js 18 or newer, per the README. After that any MCP client can launch it with npx.

Does it read screenshots or the page structure? The default is the accessibility tree. Screenshots are available as a tool, and coordinate-based mouse tools are opt-in.

Can I run it without a visible window? Yes, pass --headless. The browser is headed by default.

Is it a security boundary? No. The README states that directly. Run it isolated for untrusted sites.

Should a coding agent use the MCP server or the Playwright CLI? The README steers coding agents toward the CLI with skills for token efficiency, and keeps MCP for persistent, exploratory loops.

*Product names are used descriptively. We are not affiliated with Microsoft or Playwright.*