What Is Playwright MCP? How It Works and How to Install It

Introduction

Playwright MCP is the bridge between an AI agent and real, rendered web pages. Coding assistants and autonomous agents increasingly need to do more than read static HTML: they need to click a button, fill out a form, or confirm that a page actually looks right after a deploy. Guessing at pixel coordinates from a screenshot is a slow and brittle solution.

This guide covers what Playwright MCP actually is, how it works under the hood, and how to install it in the MCP clients you're most likely using.

It also explores where it runs into limits, including the context-window cost of exposing dozens of tools to a model, and what changes once a single local browser process isn't enough.

What is Playwright MCP?

Playwright MCP is a Model Context Protocol server, built and maintained by Microsoft, that wraps Playwright's browser automation and exposes it as a set of tools an MCP client can call directly. Model Context Protocol (MCP) is an open standard for connecting an AI model to external tools and data through a consistent interface, instead of every integration needing its own custom glue code.

Before Playwright MCP, giving an LLM control of a browser usually meant you had to make one of two compromises:

1. You fed the model raw HTML, which buries the handful of interactive elements it needs under markup it doesn't.
2. You fed it screenshots and asked a vision model to guess pixel coordinates for a click.

Both work, but neither is particularly reliable once a page becomes more complex.

Playwright MCP solves this by exposing Playwright's own browser control, navigation, clicking, typing, and form filling through MCP's tool-calling interface, and by returning structured accessibility data instead of pixels.

The result is an AI agent that can open a real browser, read what's actually on the page in a form built for machines to parse, and act on it, whether that's a coding agent verifying a UI change or a research agent pulling data from a site with no API.

It works with any MCP client: VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, and others that speak the same protocol. That breadth is part of the appeal. You configure it once per client, and the same MCP server backs every agent session you run through it.

How does Playwright MCP work?

The accessibility snapshot is core to the solution. Instead of sending the model a screenshot and asking it to guess where things are, Playwright MCP returns a structured snapshot of the page's accessibility tree: the same role, label, and state information that screen readers rely on.

Every interactive element in that snapshot gets a short reference, and the model uses that reference, not a pixel coordinate, to act.

Here's what that looks like in practice. Say an agent is asked to open a demo to-do app and add an item. The server first returns a snapshot of the page, each element tagged with a reference such as e3 or e5, including the text input where a new item gets typed.

The model reads that snapshot, picks the text input's reference, and calls a type action against it with the text to enter and a flag to submit. The server runs that action in the real browser and returns an updated snapshot, now showing the new list item and an element describing how many items are left.

The model never had to interpret a single pixel. It read labeled, structured data and acted on a reference.

That loop – snapshot, choose a reference, act, and get a new snapshot – repeats for however many steps a task needs. It's also why the MCP server doesn't need a vision-capable model to drive a browser: everything it hands the model is already text.

By default, the browser launches in headed mode, so you'll see the window open on your screen the first time you run a task – useful for watching what the agent is doing while you get used to it.

Key features of the Playwright MCP server

Beyond the core snapshot-and-act loop, the MCP server exposes a broader set of capabilities for interacting with web pages:

• Full interaction coverage. Clicking, typing, filling forms, selecting from dropdowns, hovering, dragging and dropping, and pressing individual keys are all available as discrete actions.
• Screenshots on demand. You can still request a visual screenshot of the page or a specific element when a task genuinely needs visual verification rather than structural data.
• Network monitoring and mocking. An agent can list the requests a page has made since it loaded and read console output for debugging. Mocking a route to return a custom response is opt-in and needs the --caps=network flag.
• Persistent storage state. The default browser profile is saved to disk, so logins carry over between runs. To start each session clean instead, add the --isolated flag, which keeps the profile in memory. You can then load saved cookies and local storage at startup with --storage-state, or add --caps=storage for tools that save that state to a file and restore it later.
• Arbitrary Playwright code execution. For interactions too complex for individual tool calls, the browser_run_code_unsafe tool runs a short Playwright script directly in the MCP server's process. It’s part of the default tool set, so only connect clients and agents you trust.
• Experimental WebMCP support. Pages can register their own tools through the emerging WebMCP standard, and the MCP server offers those page-defined tools to the agent alongside its built-in ones.

How to install Playwright MCP

Most MCP clients share the same standard configuration, whether you're adding it to VS Code's settings or to Claude Desktop. Add this to your client's MCP settings, and it will launch the MCP server with npx the first time it's needed:

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

You'll need Node.js 18 or newer, since the MCP server runs on Node. It also drives your installed Google Chrome by default, so if Chrome isn't on the machine, run npx playwright install chrome first (or pass --browser to pick another browser).

Claude Code

Claude Code has a dedicated CLI command that registers the MCP server for you, so you don't need to hand-edit a config file:

claude mcp add playwright npx @playwright/mcp@latest

Once it's registered, start a session and ask Claude Code to use Playwright explicitly in your first message, as it will sometimes default to running Playwright through shell commands instead of the MCP tools.

VS Code and Claude Desktop

VS Code supports a one-line CLI install through code --add-mcp with the MCP server's JSON configuration, as well as a settings-based install from inside VS Code itself.

VS Code Insiders tends to pick up new MCP features before VS Code's stable release does, so switch to it if a capability mentioned here isn't showing up yet.

Claude Desktop uses the same standard configuration block shown above, added through its own MCP settings file (claude_desktop_config.json) rather than a CLI command. Restart Claude Desktop after editing that file for the new MCP server to show up.

Whichever client you use, the browser opens in headed mode by default, which is useful for watching what the agent does while you get used to it. If you'd rather it stay hidden, add --headless to the args array.

Using Playwright MCP for automated testing and CI

Playwright MCP complements Playwright's own test runner rather than replacing it. A deterministic regression suite still belongs in Playwright Test, running the same assertions the same way on every run.

Use an AI agent for the exploratory work around that suite:

• Generating new test cases from a description of a feature.
• Investigating why a specific test failed by reading the live page instead of a static trace
• Adapting a flow after a UI change without a person rewriting every selector by hand.

Running it inside CI looks different from running it on a developer’s laptop. Instead of letting each MCP client spawn its own server, you can start the MCP server as a standalone process that listens over HTTP. CI workers usually have no display, so add --headless too:

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

Then point your MCP client at that endpoint instead of a local command:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Several clients can connect to the same server. Each gets its own browser context by default; add --shared-browser-context if you want them to share one.

Projects see the most value here when their UI changes often enough that hand-maintained locators become a maintenance burden, or when a QA team wants to explore coverage for a feature before writing a formal test for it.

Running Playwright MCP with Claude Code

Once the MCP server is registered and you’ve asked for Playwright by name, Claude Code can use browser_snapshot, the accessibility-tree call, to read a page instead of taking screenshots or writing ad hoc Playwright scripts to run through bash.

During a typical session, you ask Claude Code to navigate to a URL, read back a snapshot showing the page's headings, inputs, and buttons with their references, then tell it to click or type against one of those references.

Claude Code chains these calls itself – navigate, read the snapshot, act, and read the next snapshot – without you writing any Playwright code by hand.

The browser this launches is still a local Chromium process by default, running on whatever machine Claude Code itself is running on. It's fine for a single developer poking at a site, but is harder to justify once you need the same session running from a CI worker with no display, or need built-in protection against the bot detection a lot of production sites now run.

Running Playwright MCP against a managed browser

Playwright MCP’s configuration file accepts a browser.cdpEndpoint setting, which points the MCP server at an existing browser over the Chrome DevTools Protocol instead of launching its own local Chromium process. This file is separate from your MCP client settings:

{
  "browser": {
    "cdpEndpoint": "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN&timeout=300000"
  }
}

Save it (for example, as playwright-mcp.json) and pass its path to the server with the --config flag in your client settings:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--config", "path/to/playwright-mcp.json"]
    }
  }
}

That single setting lets you run Playwright MCP against a cloud Playwright browser you don't have to install or maintain yourself. Browserless documents a version of this specifically for Claude Code, registering the same @playwright/mcp package but passing the connection string as a command-line flag instead of a config file:

claude mcp add playwright-browserless \
  -- npx -y @playwright/mcp@latest \
  --cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true&timeout=300000"

The timeout=300000 parameter keeps the session open for five minutes; Browserless’s default is 30 seconds.

The /stealth segment in that URL routes the session through anti-detection handling at the infrastructure level, and solveCaptchas=true turns on automatic CAPTCHA solving for the session. Solving can take up to a minute, so Browserless recommends adding a short note to your project’s CLAUDE.md telling Claude Code to wait rather than interact with a CAPTCHA itself.

You can add proxy=residential to the same URL to route traffic through residential proxies, or swap production-sfo for production-lon or production-ams to run closer to Europe. If you see connection timeouts while a browser starts up, add --cdp-timeout 60000 to the server args.

Everything above it in this guide – the standard config, the tool list, the snapshot-and-act loop – works exactly the same; only where the browser physically runs has changed.

Playwright MCP vs. Playwright CLI

If you’re working with a coding agent such as Claude Code, Playwright MCP isn’t the only path Microsoft offers. In fact, the alternative skips the Model Context Protocol entirely.

Coding agents that need to stay token-efficient across a large codebase can use a separate CLI-plus-skills approach, which avoids loading a full MCP tool schema and a verbose accessibility tree into every turn.

Playwright MCP earns its keep in the opposite case: an agentic loop that benefits from persistent browser state and iterative reasoning over a page's structure across many turns, such as exploratory testing or a long-running research task. Neither replaces the other. Which one fits depends on the shape of the agent you're building, not on which is newer.

Playwright MCP's limitations

Of course, Playwright MCP is not a universal fit.

The code-execution tool mentioned earlier comes with a warning: Microsoft describes running arbitrary Playwright code in the MCP server’s process as equivalent to remote code execution. Because it ships in the default tool set, only connect MCP clients you trust completely.

A headless browser the MCP server launches itself is also closed automatically after an hour without a completed tool call. The next tool call relaunches it, but the page the agent was working on won’t still be open. You can change or disable the limit with --idle-timeout; it doesn’t apply to headed browsers or to a browser you connect to over CDP.

In the current release (0.0.83), Playwright MCP loads 25 tool definitions by default, rising to 72 once you switch on every optional capability with --caps, such as vision or devtools.

Each definition sits in the model's context before a single browser action happens. It's not a flaw so much as a result of the design: fine-grained tools give an agent more precise control, at the cost of context a single do-everything tool wouldn't spend. Whether that cost is worth it hinges on how much of your context budget the rest of the task already needs.

Conclusion

Playwright MCP gives an AI agent a genuine, structured way to see and act on real web pages, without the fragility of pixel-guessing or the dead end of raw HTML.

It's a solid default for coding agents, exploratory testing, and research tasks that need to reason over a page's structure across multiple turns, and it takes a few minutes to install in VS Code, Claude Code, or Claude Desktop.

It starts to strain at scale: a local Chromium process that one developer launches on demand isn't the same thing as a browser that needs to survive a CI run or get past the bot detection a production site throws at it.

Pointing its cdpEndpoint at a managed browser enables you to keep the same tool calls and the same accessibility-snapshot workflow while handing the browser itself, and the stealth and CAPTCHA handling around it, to infrastructure built for that job.

If you're at that point, try Browserless's free plan to test it against your own setup before committing to anything bigger.

Playwright MCP FAQs

Is Playwright MCP free?

Yes. It's released as an open-source package under Microsoft's own repository, so there's no license cost to install and run it yourself. Your costs come from elsewhere: the AI model’s token usage and, if you use one, a managed browser service.

What's an MCP server for?

An MCP server exposes a specific set of tools or data to an MCP client through the Model Context Protocol's standard interface, so the model doesn't need a custom integration built for every service it talks to.

Playwright MCP happens to expose browser control; other MCP servers expose things like file systems or internal databases in the same way.

Is Playwright obsolete?

No. Playwright MCP is built on top of Playwright, not a replacement for it. Playwright remains the underlying automation library actually driving the browser; MCP is simply the layer that lets an AI agent call into it.