Playwright MCP Server: Setup, Flags and Uses

October 27, 2026

The Playwright MCP server lets an AI agent drive a real browser. Your agent can open a page, click, type, fill forms, read console errors and take screenshots, all through Microsoft's Playwright automation library.

What makes it different from most browser agents: it doesn't look at the page as a picture. It reads the page's accessibility tree, a structured list of buttons, links, fields and text, and acts on those elements by reference. No vision model needed.

The essentials, from the official microsoft/playwright-mcp repository as of October 2026:

License: Apache 2.0.
Requirement: Node.js 18 or newer, plus any MCP client.
Package: @playwright/mcp, usually run with npx @playwright/mcp@latest.
Default mode: a headed browser with a persistent profile, so logins survive between sessions.
Not a security boundary: the README says so in as many words.

Below: what it does, how to install it in the common clients, the flags worth knowing, and when you should reach for something else.

What the Playwright MCP server does

The Model Context Protocol gives an AI client a standard way to call outside tools. The Playwright MCP server wraps a browser in that protocol, so any MCP-capable agent gets browser tools without custom glue code.

Accessibility snapshots vs screenshots

Most "computer use" agents take a screenshot, guess where a button is, and click a coordinate. That works, but it's slow, needs a vision-capable model, and breaks when a layout shifts.

Playwright MCP takes a different route. Its core tool, browser_snapshot, captures the page's accessibility snapshot, and the tool's own description calls this "better than screenshot." The agent sees something closer to an outline: a heading here, a text field labelled Email there, a button named Submit. Each element gets a reference the agent passes back when it wants to click or type.

The README lists three benefits: it's fast and lightweight, it works with models that have no vision capability, and actions are deterministic because the agent targets a specific element instead of a pixel. Screenshots still exist (browser_take_screenshot), but the tool description notes you can't perform actions based on them. They're for you to look at, or for the model to check visual layout.

If you do want pixel-based control, the --caps=vision flag turns on coordinate-based mouse tools.

The tools it exposes

The README groups the tools into categories. You don't need the full list, but knowing the groups helps you decide which capabilities to turn on.

Tool group	What it covers	Enabled by
Core automation	Navigate, click, type, fill forms, hover, drag, select options, upload files, handle dialogs, wait for text, read console messages and network requests, snapshot, screenshot	Default
Tab management	Open, close, list and switch tabs	Default
Coordinate-based	Mouse click, drag, move and wheel at x/y positions	`--caps=vision`
PDF generation	Save the page as a PDF	`--caps=pdf`
DevTools	Tracing, video recording, element highlighting	`--caps=devtools`
Network, storage, test assertions, config	Request routing, cookie and localStorage control, `verify_*` assertions, locator generation	Opt-in groups marked in the README's Tools section

One core tool deserves a warning label: browser_run_code_unsafe runs a Playwright code snippet, and the README describes it as executing arbitrary JavaScript in the server process and "RCE-equivalent." Keep that in mind when you decide which tool calls to auto-approve.

How to install the Playwright MCP server

Every client uses the same underlying command. The README's standard config, which works in most tools, is:

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

Claude Code

One command from the README:

claude mcp add playwright npx @playwright/mcp@latest

To pass server flags, use the -- separator from Claude Code's MCP docs, which keeps Claude's own options apart from the server command: claude mcp add playwright -- npx @playwright/mcp@latest --headless. For scopes, project-level .mcp.json files and troubleshooting, see our Claude Code MCP server configuration guide.

VS Code

The README offers a one-click install button, or the VS Code CLI:

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

After that, the server is available to the GitHub Copilot agent in VS Code.

Cursor

Use the install button in the README, or go to Cursor Settings, then MCP, then Add new MCP Server. Pick the command type and enter npx @playwright/mcp@latest.

Claude Desktop

The README points to the MCP quickstart for users and the standard config above. Add the playwright block to Claude Desktop's MCP config file and restart the app.

The README also covers Codex, Cline, Windsurf, Gemini CLI and others.

Running it as a standalone HTTP server

If your client runs somewhere without a display, or you want one server shared across tools, start it with a port:

npx @playwright/mcp@latest --headless --port 8931

--port only switches on HTTP transport; the browser is still headed unless you add --headless. If you want a visible browser, drop --headless and run the server from an environment that has a display (with DISPLAY set), as Microsoft's standalone-server instructions describe. Then point the client at http://localhost:8931/mcp with a url entry instead of a command. Microsoft also publishes a Docker image, which the README notes only supports headless Chromium at the moment.

Playwright MCP flags worth knowing

The README's configuration table has dozens of options. These are the ones most people need, all taken from the current table:

Flag	What it does
`--headless`	Runs the browser headless. Headed is the default
`--browser`	Picks the browser or Chrome channel: `chrome`, `firefox`, `webkit` or `msedge`
`--isolated`	Keeps the browser profile in memory and doesn't save it to disk
`--user-data-dir`	Sets the directory for the browser profile
`--storage-state`	Loads cookies and local storage from a file into an isolated session
`--caps`	Enables extra tool groups. The flag table lists `vision`, `pdf` and `devtools`
`--allowed-origins` / `--blocked-origins`	Allow or block origins the browser may request. The README says neither is a security boundary
`--device`	Emulates a device, for example "iPhone 15"
`--viewport-size`	Sets the viewport, for example "1280x720"
`--config`	Loads options from a JSON config file

Add flags to the args array after the package name, for example ["@playwright/mcp@latest", "--headless", "--browser", "firefox"].

Persistent profile vs isolated sessions

This choice matters more than any other flag.

Persistent profile (the default). The README's User profile section says Playwright MCP runs with a persistent profile like a regular browser. Logins and cookies are stored on disk and survive between sessions. On macOS the profile lives under ~/Library/Caches/ms-playwright/, with one directory per browser channel and workspace, so different projects get separate profiles. Use --user-data-dir to put it somewhere else. (The flag table's own wording says a temporary directory is created when --user-data-dir isn't set; the User profile section is the more detailed description.) A persistent profile can only be used by one browser at a time, so two clients in the same workspace will conflict.

Isolated (--isolated). Each session starts with a clean profile held in memory. When the browser closes, all its storage is gone. To start an isolated session already logged in, pass a saved storage-state file with --storage-state. Playwright's authentication docs explain how to produce one.

Browser extension (--extension). Connects to your existing Chrome or Edge tabs through the Playwright extension, using your real logged-in sessions.

A good default for most people: --isolated for anything exploratory, a dedicated persistent profile only for sites where you deliberately want the agent logged in.

What people use Playwright MCP for

Writing tests. Describe a user flow in plain language, let the agent walk through it in a real browser, and ask it to turn the steps into a Playwright test. The --codegen flag sets the output language, TypeScript by default.

Debugging your own frontend. Point the agent at localhost, have it reproduce a bug, then read the console messages and network requests it captured. This closes the loop for coding agents: change the code, reload, check the result, without you copying errors back and forth.

Checking a deploy. Have the agent click through the critical paths on a preview build and report anything broken.

Pulling data from your own sites and tools. Internal dashboards with no API, admin panels, your own staging environment. Stick to sites you own or have permission to automate, and respect their terms.

For a wider view of where this fits next to Selenium, Puppeteer and no-code recorders, see our web automation tools guide.

Security caveats before you connect it

The README is blunt: Playwright MCP is not a security boundary. It's a browser under an AI agent's control, which means:

It can use your cookies. With a persistent profile or the extension, the agent acts as you on every site you're logged into. A prompt injection on a page it visits could try to steer it toward your email or your admin panel.
Origin filters aren't a fence. --allowed-origins and --blocked-origins help steer the browser, but the README says they don't serve as a security boundary and don't affect redirects.
File access is limited by default. Access is restricted to workspace roots, and file:// navigation is blocked unless you pass --allow-unrestricted-file-access. Don't pass it casually.
Code execution exists. browser_run_code_unsafe is RCE-equivalent. Don't auto-approve it.
Network exposure. In HTTP mode the server binds to localhost by default. Binding to 0.0.0.0 exposes it to your network.

Practical rules: prefer --isolated, keep agent profiles separate from your personal browser, review tool calls on sensitive sites, and read the MCP security best practices the README links to. Our post on MCP security risks covers the broader threat model.

Playwright MCP vs ExecuteAutomation, Playwright CLI and Test Agents

Search for "Playwright MCP" and you'll find several different things:

Option	Who makes it	What it is
`@playwright/mcp`	Microsoft (Playwright team)	The official MCP server covered in this guide, built on accessibility snapshots
`@executeautomation/playwright-mcp-server`	ExecuteAutomation, a community project	A separate MCP server that also uses Playwright, with screenshot, scraping, test-code and JavaScript tools
Playwright CLI with skills	Microsoft	A CLI the README suggests for coding agents, since it avoids loading large tool schemas and accessibility trees into context
Playwright Test Agents	Microsoft, inside Playwright Test	Planner, generator and healer agents set up with `npx playwright init-agents`

The README is candid about the split with its own CLI. It says coding agents increasingly favor CLI workflows because they're more token-efficient, while MCP stays relevant for longer agentic loops that benefit from persistent browser state, such as exploratory automation and self-healing tests.

Playwright Test Agents are narrower. The planner explores your app and writes a Markdown test plan, the generator turns the plan into Playwright test files, and the healer runs the suite and repairs failing tests. If your goal is test coverage, start there. If you want an agent that can browse and act in general, use the MCP server.

Where Taku fits

Getting an MCP server like this wired into the right client, with the right flags, is often the step where a promising agent setup stalls. Taku is an AI-native desktop workspace that mirrors a working AI setup and runs it, so you can start from a configuration someone already got working rather than rebuilding it. Taku is in Beta, and the Mac app is available now. If you're still picking servers, our best MCP servers roundup is a good next read.

FAQ

What is the Playwright MCP server?

It's Microsoft's official MCP server for browser automation. It lets AI agents control a real browser through Playwright, using structured accessibility snapshots instead of screenshots.

Is Playwright MCP free and open source?

Yes. The microsoft/playwright-mcp repository is licensed under Apache 2.0.

How do I add Playwright MCP to Claude Code?

Run claude mcp add playwright npx @playwright/mcp@latest. To add server flags like --headless or --isolated, put -- before the command: claude mcp add playwright -- npx @playwright/mcp@latest --isolated.

Does Playwright MCP need a vision model?

No. It works on the accessibility tree, so any model that can call tools can use it. Vision-style coordinate tools are optional via --caps=vision.

Can Playwright MCP run headless?

Yes. It runs headed by default; add --headless to hide the browser window.

Does Playwright MCP keep me logged in?

By default it uses a persistent profile, so logins survive between sessions. Use --isolated for a fresh in-memory profile each session, or --storage-state to load a saved login into an isolated session.

Is the Playwright MCP server safe?

It's as safe as the browser profile you give it. The README states it is not a security boundary. Use isolated sessions, keep it away from your personal logins, and don't auto-approve code execution.

Key points

Playwright MCP is Microsoft's Apache-2.0 MCP server for browser automation, and needs Node.js 18+.
It acts on accessibility snapshots, not screenshots, so it's deterministic and works without vision models.
Install with npx @playwright/mcp@latest in any MCP client; Claude Code uses claude mcp add.
--headless, --browser, --isolated, --user-data-dir and --caps are the flags most setups need.
The default persistent profile keeps logins; --isolated is safer for exploration.
It is not a security boundary, so treat it like handing an agent your browser.