Playwright MCP Server: Setup, Tools, and Token Costs (2026)

The Playwright MCP server drives a real web browser for AI assistants through the Model Context Protocol (MCP), the open standard Anthropic created in November 2024. Microsoft builds and maintains the server on top of its Playwright automation library, and the repository holds over 33,000 GitHub stars as of mid-2026. Claude Code, Cursor, VS Code, and Codex connect to it and navigate pages, click elements, fill forms, and extract content in natural language.

One design choice separates it from every screenshot-based browser agent: the server snapshots the page as a structured accessibility tree, a text representation of element names, roles, and references. The model reads structure, not pixels, so it targets exact elements without a vision model and without the cost of interpreting images.

The server launches locally through npx, speaks stdio to the client, and controls Chromium, Firefox, WebKit, or Edge. This page covers the tool set and the snapshot mechanism, the three session modes that decide how the browser handles your logins, the exact configuration per client, the failures you hit and their fixes, the snapshot token problem, and the honest 2026 answer on when Microsoft’s own Playwright CLI beats this server.

All browser automation MCP servers · What MCP is and how it works

What Does the Playwright MCP Server Expose?

The Playwright MCP server exposes more than 20 browser tools in four families: navigation, interaction, observation, and debugging. The model navigates to URLs, clicks and types against exact element references, reads page snapshots, and captures console and network activity.

Tool family	Representative tools	What the model does with them
Navigation	`browser_navigate`, `browser_tabs`	Opens URLs, moves through history, switches tabs
Interaction	`browser_click`, `browser_type`, `browser_fill_form`	Clicks, types, selects, and submits against element refs
Observation	`browser_snapshot`, `browser_take_screenshot`	Reads the accessibility tree; captures pixels when asked
Debugging	`browser_console_messages`, `browser_network_requests`	Reads console errors and network traffic

The accessibility tree is the mechanism behind all four families. Each snapshot returns the page as named elements with roles and reference IDs: a “Submit order” button, a “Email address” textbox, a “Pricing” link. The model picks the ref and acts on it. A screenshot-driven agent guesses coordinates from pixels; this server addresses elements the way assistive technology does, which makes actions deterministic and repeatable.

Here is the loop on a real prompt, “log into the dashboard”:

browser_navigate  → https://app.example.com/login
browser_snapshot  → textbox "Email" [ref=e12] · textbox "Password" [ref=e13] · button "Sign in" [ref=e14]
browser_type      → ref e12, "you@example.com"
browser_type      → ref e13, "********"
browser_click     → ref e14
browser_snapshot  → heading "Dashboard" [ref=e3] confirms the logged-in state

The model reads named refs, acts on them, and verifies from the next snapshot. No pixels were interpreted at any step.

Beyond the four families, the tool set covers file uploads, dialog handling, JavaScript evaluation on the page, hover and drag interactions, and tab management, which is why the count sits above 20 and grows with releases.

The output side completes the loop. The server saves pages as PDFs, captures verification screenshots on request, and exports recorded actions as native Playwright test scripts, so an exploration session ends as a runnable test file.

Four workflows show what the tool set produces in practice:

Agentic test generation. “Explore the checkout flow and write tests for it” sends the model through the pages via snapshots, and the session exports as a runnable Playwright test suite, the zero-code path to E2E coverage.
Verify-after-edit loops. A coding agent modifies a React component, opens the localhost dev server, fills the form, submits, and confirms the change broke nothing. GitHub Copilot’s Coding Agent runs this loop with the server preconfigured.
Local web scraping. The model navigates a JavaScript-heavy, multi-page app and extracts structured data, with the browser and the data staying on your machine.
Exploratory debugging. “Open the dashboard and tell me why the chart is empty” chains navigation with browser_console_messages and browser_network_requests: the model reads the real error and the failing request instead of guessing.

What Are the Three Session Modes?

The server runs in three session modes: persistent (the default) keeps logins between sessions, isolated starts every session clean, and browser extension drives the tabs of your existing logged-in browser. The mode decision is the authentication decision: it sets where your cookies live and what the model can reach with them.

Mode	Flag	State behavior	Fits
Persistent	none (default)	Cookies, logins, and local storage survive between sessions in a per-project profile	Daily work against apps you log into once
Isolated	`--isolated`	Every session starts clean and wipes on close; `--storage-state` seeds initial cookies	Test runs, sensitive workflows, parallel sessions
Browser extension	`--extension`	Connects to your running browser’s tabs and uses its real logged-in state	Authenticated flows without re-implementing login

Two details in the persistent default matter. The profile lives at ms-playwright/mcp-{channel}-{workspace-hash} in your platform’s cache directory, and the workspace hash means each project gets a separate profile automatically: logging into staging from project A never leaks into project B. Override the location with --user-data-dir, and delete the directory to reset the stored state (playwright.dev, MCP docs, 2026).

The extension mode is the newest path: an official Playwright MCP extension in the Chrome Web Store acts as a bridge between the server and a running Chrome window, so the model drives a tab that already holds your real session. Install the extension, launch the server with --extension, and pick the tab to hand over. The convenience and the risk are the same fact, and the security section below prices it.

How Do You Set Up the Playwright MCP Server?

Set up the Playwright MCP server by adding one npx command to your client’s config: npx @playwright/mcp@latest. The package downloads on first run. The browser binaries do not: run npx playwright install once, because the browsers are a separate download, and skipping this step is the most common first failure.

The base config every client variant builds on:

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

Append mode and scope flags to args as needed: --isolated for clean sessions, --allowed-origins to whitelist the domains the browser can reach, --blocked-origins to fence specific domains off. Advanced setups pass --config path/to/config.json for browser options, network rules, and timeouts.

Claude Code

Add the server with one command:

claude mcp add playwright npx @playwright/mcp@latest

The tools register at the next session start. The full client walkthrough is at set up MCP in Claude Code.

Cursor

Add the base config block to .cursor/mcp.json at the project root, with STDIO as the type where Cursor’s UI asks. The config travels with the repository, and the persistent profile’s workspace hash gives the project its own browser state. Client-side steps are at add MCP servers to Cursor.

VS Code and GitHub Copilot

VS Code configures the server natively under its "servers" root key, not "mcpServers". The Copilot Coding Agent ships with Playwright MCP configured automatically, no setup required: the agent reads, interacts with, and screenshots pages on localhost during code generation, which is the verify-after-edit loop in production form (TestCollab, February 2026).

Claude Desktop

Claude Desktop takes the base config block in claude_desktop_config.json, then requires a full application quit and relaunch: the config loads at startup only, and a closed window does not reload it. The chat-client pairing fits exploration and scraping more than test generation, since the exported test files land in the working directory the server was launched from. The walkthrough is at set up MCP in Claude Desktop.

Codex CLI, Gemini CLI, and other clients

Codex CLI registers the server in ~/.codex/config.toml with the same npx command. Gemini CLI, Windsurf, OpenCode, and Cline take the identical command in their respective config files. Every client’s exact file path is in its setup guide.

Docker

Microsoft publishes an official image at mcr.microsoft.com/playwright/mcp. One constraint governs it: the Docker implementation supports headless Chromium only (microsoft/playwright-mcp README). Containerize for CI and remote runs; develop locally when you need Firefox, WebKit, or a headed window.

Which browsers does it drive?

The server controls Chromium, Firefox, WebKit, and Edge, with Chromium as the default. The --browser flag selects the engine, and a channel value such as chrome or msedge targets an installed branded browser instead of the downloaded binaries. Cross-engine coverage is the inherited Playwright advantage the archived Puppeteer server never had.

Remote and HTTP transport

The server speaks stdio by default and switches to HTTP transport with the --port flag, which exposes an endpoint a remote client connects to by URL. The HTTP path serves containerized runs, headless servers, and clients on another machine; local desktop setups stay on stdio.

Verify the connection

A working connection lists the browser tools in the client’s MCP panel, and the prompt “open example.com and tell me the page title” launches a browser and returns the real title. A visible browser window opening is the confirmation; the failures below are what you see instead.

Why Isn’t the Playwright MCP Server Working?

The four most common failures are missing browser binaries, a headed browser on a system without a display, the wrong package among three similarly named servers, and a snapshot that overflows the context window.

The server starts and every navigation fails. The browser binaries were never installed. npx @playwright/mcp@latest fetches the server, not the browsers. Run npx playwright install once and retry.
The browser never opens on a remote or containerized system. A headed browser needs a display. On systems without one, run the server from an environment with DISPLAY set, or pass the --port flag to switch to HTTP transport and run headless (microsoft/playwright-mcp README).
The tools look different from every tutorial. Three similarly named servers exist. @playwright/mcp is Microsoft’s official server and the subject of this page. @executeautomation/playwright-mcp-server is the community server that predates it, with its own tool names and flags. Playwright Test MCP is a separate Microsoft server focused on generating and running Playwright tests, not general browsing: “Playwright MCP is for automating browsers, while Playwright Test MCP is for testing” (Debbie O’Brien, Playwright team, November 17, 2025). Check which package your config launches before debugging tool behavior; the maintenance-recency rule from the server directory applies across all three.
One tool call consumes most of the context window. A full-page snapshot of a dense page returns the entire accessibility tree. This is the token problem, not a connection problem, and the next section prices it.

A connected server now drives a real browser on your machine. What that costs per call, and what it can reach, are the supplementary half of this page.

How Many Tokens Does the Playwright MCP Server Consume?

A full-page snapshot consumes 15,000 to 30,000 tokens on a dense page, the highest per-call cost of any common MCP server. The accessibility tree that makes actions deterministic is also a large text structure, and a model that snapshots after every click spends its context window on page state.

Two disciplines contain the cost. Target specific elements instead of whole pages: a click against a known ref costs a fraction of a fresh snapshot. Snapshot once per page state, run every click and input against that snapshot’s refs, and snapshot again only after the page changes.

The 2026 ecosystem shift reframes the question for one audience. Microsoft now recommends its Playwright CLI over the MCP server for coding agents, and the CLI uses 4x fewer tokens per session by piping terse command output instead of tool definitions and tree snapshots (TestDino, 2026). Independent benchmarking widens the spread: the OnlyCLI benchmark measured a 4x to 32x cost difference between CLI and MCP paths depending on the task, and GitHub runs both internally. The recommendation is honest and so is its boundary: the CLI fits coding agents that already live in a terminal, and the MCP server remains the path for chat clients, for interactive exploration where the model decides the next action from page state, and for every client without shell access. A coding-agent team should run the comparison before standardizing.

Is the Playwright MCP Server Safe?

The Playwright MCP server is safe when it browses trusted origins in an appropriate session mode. Microsoft’s own README states the boundary plainly: “Playwright MCP is not a security boundary.”

The exposure is structural. A model driving a browser reads everything on every page it visits, and page content is untrusted input: a hostile page can embed instructions the model may follow, the same prompt-injection class documented across MCP servers. The browser-specific multiplier is the session mode. A persistent profile holds your logins; the extension mode hands the model tabs that are already authenticated as you. An injected instruction in those modes operates with your cookies.

Three controls contain it:

Match the mode to the trust level. Run --isolated for any workflow that touches pages you do not control. Reserve the extension mode for trusted internal flows.
Fence the origins. --allowed-origins limits the browser to a whitelist; an injected redirect to an attacker’s domain fails at the flag.
Keep approval friction on. Clients require per-call approval for tool use, and the protection holds exactly as long as you read what you approve.

Should You Use the Playwright MCP Server or the Puppeteer MCP Server?

Use the Playwright server as the default, and the Puppeteer server only when an existing Puppeteer codebase anchors you to it. The Playwright server is Microsoft-maintained, current with the protocol, cross-browser across Chromium, Firefox, and WebKit, and built on the accessibility-tree model. The archived Puppeteer reference server is Chromium-only and no longer updated, which fails the maintenance-recency test on its own.

Playwright MCP Server Questions

Is the Playwright MCP Server Free?

Yes. The server is open-source under the Apache 2.0 license, and the npm package, the Docker image, and the Chrome extension are free. The costs it creates are indirect: the tokens its snapshots consume in your AI client, and the compute of running real browsers.

Is the Playwright MCP Server by Microsoft?

Yes. Microsoft builds and maintains the server in the microsoft/playwright-mcp repository, on top of its Playwright automation library. The similarly named @executeautomation/playwright-mcp-server is a community project, and Playwright Test MCP is a second Microsoft server focused on test generation and execution.

What Is the Difference Between Playwright and Playwright MCP?

Playwright is a browser automation library developers script in code. The Playwright MCP server wraps that library and exposes it to AI models as callable tools. With the library, you write the automation. With the server, the model writes it: you describe the goal in natural language, and the model navigates, clicks, and extracts through tool calls.

Is the Playwright MCP Server Better Than Selenium?

For AI-driven automation, yes. Selenium has no official MCP server, no accessibility-tree snapshot model, and community Selenium MCP wrappers expose a thinner tool set. Selenium remains a scripting library for human-written tests; the Playwright server is built for a model to drive. Teams with existing Selenium suites keep them for regression and add this server for the agentic workflows the suites cannot cover.

Can the Playwright MCP Server Take Screenshots?

Yes. The browser_take_screenshot tool captures pixels on request, and the server saves pages as PDFs. Screenshots are the exception, not the mechanism: the model acts from accessibility-tree snapshots, and captures images for human verification, visual records, and the cases where structure alone cannot answer.

Every answer on this page runs through the same structure: a snapshot of named elements, a ref, an action, a result. Configure the mode before the first navigation, fence the origins, and the server that can drive any page on the web drives exactly the pages you pointed it at.

What Does the Playwright MCP Server Do and How Do You Set It Up?