Playwright MCP: Browser Automation for AI Agents (2026)

TL;DR

Three constants worth memorising if Playwright MCP ends up in your agent stack:

• NPM package: @playwright/mcp — published by Microsoft, Apache-2.0 licensed, source at github.com/microsoft/playwright-mcp.
• Default browser: Chromium, headed. Switch with --browser=firefox|webkit|chrome|msedge and run headless with --headless.
• Killer feature: the agent operates on the page’s accessibility tree, not screenshots. Faster, cheaper, more reliable than any vision-model competitor.

One-line installs:

• Claude Code: claude mcp add playwright npx @playwright/mcp@latest
• Cursor / VS Code: use the 1-click buttons in our Playwright server page or paste the JSON snippet emitted by the install panel below.
• OpenCode / Codex CLI: snippets in the install section — both use npx -y @playwright/mcp@latest under the hood.

The rest of this post explains why the accessibility tree matters, walks through every tool group with real example calls, hands you seven recipes for common automation jobs, and ends with a head-to-head between Playwright MCP and the obvious competitors (Puppeteer MCP, Chrome DevTools MCP, the various Firecrawl-style scraping APIs).

What Playwright MCP actually does

Playwright MCP is a wrapper around Microsoft’s Playwright library — the same automation framework used by tens of thousands of test suites at companies like Disney, Adobe, and most of the cloud infrastructure ecosystem — exposed over the Model Context Protocol so an AI agent can drive a browser directly. You don’t write Playwright code; the agent calls Playwright primitives by name. The MCP server translates each tool call (browser_navigate, browser_click, browser_type) into the Playwright API call that does the work.

Under the hood it spawns a real browser instance — Chromium by default, with Firefox, WebKit, Chrome, and Edge available via flag — and keeps that instance hot between tool calls so the agent can chain navigation, clicks, and form fills as a single stateful session. Tabs persist. Cookies persist. Auth state persists. The agent is essentially a power user clicking around your application, except every action is logged, every decision is grounded in a snapshot of the DOM, and the whole thing replays the same way next time.

The package lives at npmjs.com/package/@playwright/mcp and the source is at github.com/microsoft/playwright-mcp — Apache-2.0 licensed, maintained directly by the Playwright team at Microsoft. That maintainer pedigree matters: Playwright the library ships weekly, every flake fix and new browser feature lands first there, and the MCP server gets dragged along on the same release train. Compare that to MCP servers maintained by a single hobbyist who’s three commits behind the upstream API.

The headline use cases we see in the wild: agent-driven end-to-end testing (let an LLM write and run the test suite), web scraping behind login walls, automating browser-only workflows like the cell-by-cell editing in Google Sheets, taking screenshots and PDFs of dashboards on a schedule, and the “ChatGPT plus a browser” research workflow where the agent reads docs, navigates between pages, and synthesises the results.

Compare that to what the same task looks like without an MCP layer. You either write Playwright test files by hand (slow, brittle, every new flow is a new file), or you give a vision model screenshots and pray it clicks the right pixel (slow, expensive, fundamentally non-deterministic). The MCP layer turns Playwright from a library humans drive into a library agents drive — every action stays in the same chat turn, every error feeds back into the same context, and the agent can blend “think about the next step” and “take the next step” into one fluid loop.

Worth saying explicitly: this is the first MCP server most teams should install for any browser-touching agent workflow. Even if you end up swapping it out later for a specialised crawler like Firecrawl, the Playwright MCP is the Swiss-army-knife. Install it once at user scope, give the agent permission, and you’ve covered 80% of what people mean when they say “I want my agent to use a browser”.

Accessibility tree vs screenshots — the killer differentiator

Most browser-automation MCP servers fall into one of two camps. The vision camp (Anthropic’s Computer Use, a handful of independent Puppeteer wrappers) takes a screenshot every step, feeds the pixels to a vision model, lets the model output x,y coordinates, and clicks there. The DOM camp (Playwright MCP, Chrome DevTools MCP) skips the screenshot and hands the model a structured description of the page instead.

Playwright MCP’s default snapshot uses the accessibility tree — the same data structure a screen reader uses to describe the page to a blind user. Every interactive element has a role (button, link, textbox), an accessible name (the visible label or the aria-label), a state (focused, expanded, checked), and a stable reference the agent can pass to browser_click or browser_type. The model sees this:

- banner
  - link "MCP.Directory home" [ref=e7]
  - navigation
    - link "Servers" [ref=e12]
    - link "Skills" [ref=e13]
- main
  - heading "Browse MCP servers" [level=1]
  - searchbox "Search servers" [ref=e24]
  - button "Filter by category" [ref=e25]

Then it picks ref=e24, calls browser_type(ref="e24", text="Playwright"), and the right thing happens. No coordinates. No guessing. No “the model clicked the wrong button because the layout shifted by 12 pixels between snapshots”.

Why this matters in practice: it’s a different order of magnitude on three axes. Speed: screenshots are slow to generate, slow to transmit to the model, and slow to reason about. The accessibility tree is text — a few KB versus a few MB. Cost: vision tokens are ~3-5x more expensive than text tokens on every major API. Browser-automation runs that consume 50,000 vision tokens consume 5,000 text tokens with the accessibility tree. Determinism: vision models guess coordinates and miss; the accessibility tree gives the agent a stable reference. We’ve watched test suites flake out because a vision-based agent clicked the wrong pixel; the same suite under Playwright MCP runs green for weeks.

There’s a tradeoff. If your target page is a canvas-rendered application (Figma, a WebGL game, anything that doesn’t expose DOM semantics), the accessibility tree is empty and you’re stuck. For those cases Playwright MCP has the --caps=vision capability flag which unlocks coordinate-based mouse primitives (browser_mouse_click_xy, browser_mouse_move_xy) and you can mix the two modes. But for the 95% of web automation that operates on real HTML, the tree wins every time.

The Playwright team also wraps a vision snapshot fallback (browser_take_screenshot) so the model can grab pixels when it needs to verify visual state — text colour, image rendering, a modal’s arrival animation. That hybrid is what makes Playwright MCP feel more capable than either pure-vision or pure-DOM competitors.

Browser selection: Chromium, Firefox, WebKit

Playwright the library has always had three first-class engines, and Playwright MCP inherits all three. The --browser flag picks which one launches:

• --browser=chromium — the default. Use this unless you have a reason not to. Chromium covers Chrome, Edge, Brave, Opera, and Arc.
• --browser=firefox — Mozilla’s engine. Worth picking when you’re testing Firefox-specific behaviour or your target site blocks Chromium UA strings.
• --browser=webkit — the engine underneath Safari. The closest thing to running “real Safari” in headless CI without paying for macOS runners.
• --browser=chrome, --browser=msedge — branded channels that use the host machine’s installed Chrome or Edge binary. Useful when you need exactly the user’s shipping browser, not a Playwright-bundled Chromium.

First-run, each engine needs its binary downloaded. The agent can do this on demand with the browser_install tool, which fetches the Playwright browser bundle for whichever engine you pick. Alternatively, run npx playwright install chromium firefox webkit upfront so the agent never has to wait.

One pattern we like: pin a per-project browser by passing the flag in the MCP server registration. For example, an iOS-leaning project might register Playwright MCP with -- --browser=webkit so every agent action automatically runs in the engine your users actually use. For most teams Chromium is the pragmatic default — same engine as Google’s Lighthouse, easier to debug, smaller download.

Install (every client)

The Playwright MCP install pattern is the same for every client: spawn npx @playwright/mcp@latest as a stdio subprocess and let the client connect to it. There’s no remote endpoint to point at — the server runs locally, drives a local browser, and exits when the agent disconnects.

For the standard clients — Claude Code, Cursor, VS Code, Claude Desktop, Codex CLI, Windsurf, Gemini CLI — the install panel below has the exact one-click button or copy command. Tap your client, paste, restart, and Playwright shows up in the tool catalogue. The panel pulls its configs from our catalog and stays in sync as Playwright MCP ships new transport options.

One-line install · Playwright Browser Automation

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

The Claude Code one-liner deserves its own paragraph because it’s the single most-typed command in this whole guide:

claude mcp add playwright npx @playwright/mcp@latest

Add --scope project to write to .mcp.json at the repo root so the server travels with the project. To run headless, append -- --headless to the install command (the double-dash forwards everything after it to the Playwright CLI). To swap the default browser to WebKit: claude mcp add playwright npx @playwright/mcp@latest -- --browser=webkit --headless. Full client roster lives at mcp.directory/clients, including the Claude Code page and the Cursor page for client-specific gotchas.

Add Playwright MCP to OpenCode

OpenCode (the open-source TUI agent) reads MCP servers from its user config — commonly ~/.config/opencode/config.json. Run opencode config print to confirm the path on your install. The shape:

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp@latest"]
    }
  }
}

For a specific browser plus headless mode, extend the args array:

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx", "-y", "@playwright/mcp@latest",
        "--browser=firefox", "--headless"
      ]
    }
  }
}

Restart OpenCode and Playwright’s tools show up in the tool list. If you’re comparing OpenCode against Claude Code, Aider, Cline, or Goose, our CLI agent comparison covers the trade-offs.

Add Playwright MCP to Codex CLI

Codex CLI reads its MCP server config from ~/.codex/config.toml. Add this block:

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

For headless WebKit (a common pattern for CI):

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest", "--browser=webkit", "--headless"]

Restart the Codex CLI session, and Playwright’s tools surface to the model alongside the file-system and shell tools Codex ships with.

The tool surface, walked through

Playwright MCP exposes one of the widest tool surfaces of any MCP server — over 50 tools when you turn on every capability group. The README organises them into groups; we’ll do the same, starting with the always-on core and moving outward into the opt-in capabilities (network, storage, devtools, vision, pdf, testing).

Core automation (always on)

This is the bread-and-butter set the agent uses for 95% of web tasks:

• browser_navigate — go to a URL. Example: browser_navigate(url="https://mcp.directory"). Returns the loaded page’s title and a fresh snapshot.
• browser_navigate_back — equivalent to pressing the back button.
• browser_snapshot — capture the accessibility tree of the current page. The agent usually calls this after navigation or before deciding what to interact with.
• browser_click — click an element by ref. Example: browser_click(ref="e24", element="Search box"). The element arg is a human description that ends up in error messages — it helps debugging when the click fails.
• browser_type — type text into an input. browser_type(ref="e24", text="hello", submit=true) types and submits the form.
• browser_press_key — press a keyboard key. browser_press_key(key="Enter") is the most common call after typing in a search box.
• browser_hover — hover over an element. Useful for revealing menus that only appear on hover.
• browser_select_option — pick an option from a <select> dropdown by visible text.
• browser_fill_form — fill multiple form fields in one call. Takes an array of {ref, value} pairs and is much faster than calling browser_type for each field.
• browser_drag / browser_drop — drag-and-drop primitives for file uploads, list reordering, and drag-to-resize interactions.
• browser_file_upload — attach a file to a file input. browser_file_upload(ref="e30", paths=["/tmp/photo.png"]).
• browser_evaluate — run arbitrary JavaScript in the page context and return the result. Powerful and dangerous — the agent can read or write anything in the DOM.
• browser_wait_for — wait for an element to appear, disappear, or contain specific text. The replacement for blind sleep(3).
• browser_handle_dialog — accept or dismiss native browser dialogs (alert, confirm, prompt).
• browser_take_screenshot — pixel capture. Returns a PNG. Useful for visual regression checks and for showing the user what the agent sees.
• browser_resize — resize the viewport. Common before responsive testing.
• browser_console_messages — read console output. Useful for catching JS errors the agent might otherwise miss.
• browser_tabs — list, open, close, and switch between tabs.
• browser_close — close the browser.
• browser_install — install a missing browser binary on demand.
• browser_get_config — introspect the current Playwright MCP configuration.

Network & storage capabilities

These groups are opt-in via --caps=network and --caps=storage. Enable them when your agent needs to inspect or mock network traffic, or read/write cookies and localStorage.

• browser_network_requests / browser_network_request — list all network requests or inspect one in detail. The agent reads response bodies, headers, and timings.
• browser_route / browser_unroute / browser_route_list — install request-interception routes. Mock an API endpoint to return canned data, block third-party scripts, or rewrite a request before it goes out. This is the killer feature for testing flaky external dependencies.
• browser_network_state_set — toggle online/offline state.
• browser_cookie_get, browser_cookie_set, browser_cookie_list, browser_cookie_delete, browser_cookie_clear — full cookie CRUD. Pre-set an auth cookie before navigation for the simplest possible login bypass.
• browser_localstorage_* and browser_sessionstorage_* — same shape as cookies, for the two Web Storage APIs.
• browser_storage_state / browser_set_storage_state — dump or restore the full storage state (cookies + localStorage + sessionStorage) as a single JSON object. Pair with --storage-state on startup for persistent auth.

DevTools & vision capabilities

Enable with --caps=devtools and --caps=vision respectively.

• browser_highlight / browser_hide_highlight — draw a coloured rectangle around an element on the live page. Great for showing the user what the agent is about to interact with.
• browser_annotate — add text labels to highlighted elements. Combine with highlight for self-narrating runs.
• browser_start_video / browser_stop_video / browser_video_chapter — record screen video of the session. The chapter tool inserts markers so post-hoc review can jump to specific moments.
• browser_start_tracing / browser_stop_tracing — capture a Playwright trace. Open the resulting .zip in the Playwright Trace Viewer to debug exactly what happened.
• browser_resume — used after a trace-related pause. Resume the run.
• browser_mouse_click_xy, browser_mouse_move_xy, browser_mouse_drag_xy, browser_mouse_down, browser_mouse_up, browser_mouse_wheel — raw coordinate-based mouse primitives. The fallback when the accessibility tree gives the agent nothing to grab (canvas apps, WebGL, certain iframe-heavy sites).

PDF & testing capabilities

Enable with --caps=pdf and --caps=testing.

• browser_pdf_save — render the current page to PDF and write it to disk. Use for invoices, dashboards, contracts — anything where the visual rendering needs to be archived.
• browser_verify_element_visible, browser_verify_list_visible, browser_verify_text_visible, browser_verify_value — assertion primitives the agent uses to build E2E test cases. They throw a structured error on mismatch, which the agent reads and corrects.
• browser_generate_locator — given a visible element, generate a stable Playwright locator string the agent can write into a test file. The bridge between “agent did the thing once” and “agent generated the Playwright test that does the thing forever”.

browser_run_code_unsafe deserves its own warning. It executes arbitrary code in the Playwright runtime — anything from page.click() to spawning child processes. Only enable it when you fully trust the prompts going into the agent. It’s gated as “unsafe” in the tool name precisely because you can break out of the browser sandbox with it.

Recipes

Seven workflows where Playwright MCP earns its keep. We assume Playwright MCP is installed in your client’s tool catalogue.

Recipe 1 — Login flow with persistent storage

The single most common gotcha in agent browser automation: every fresh session is logged out. Solve it once.

First run, drive the login manually via prompt: “Navigate to app.example.com/login, fill the form with these creds, then save the storage state to ~/.auth/example.json.” The agent calls browser_navigate, browser_fill_form, then browser_storage_state with the file path. From then on, register Playwright MCP with -- --storage-state=~/.auth/example.json and every session starts already logged in.

Recipe 2 — Fill a multi-page form

Government tax forms, insurance applications, onboarding flows. Prompt: “Navigate to the application form, fill page 1 with these values, click Next, fill page 2, and so on until submit.” The agent reads each page’s accessibility tree, maps your data to the form fields, and uses browser_fill_form for batch input plus browser_click for the navigation. The accessibility-tree model handles label-to-field mapping that vision models routinely get wrong.

Recipe 3 — Scrape a protected page

Some sites lock content behind a login wall. Combine Recipe 1 (persistent auth) with browser_evaluate to extract DOM data directly. Prompt: “Log into the dashboard, navigate to the reports page, extract all rows of the ‘Q1 Revenue’ table as JSON.” The agent runs an Array.from(document.querySelectorAll(...)) snippet inside browser_evaluate, returns the data, and your downstream code consumes it. For more complex scraping at scale, look at our Firecrawl vs Anycrawl vs Crawlee vs Playwright comparison.

Recipe 4 — PDF generation from a live dashboard

Useful for reporting workflows. Prompt: “Navigate to the Grafana dashboard at this URL, wait until all panels load, then save the page as PDF to /tmp/report.pdf.” The agent uses browser_navigate, browser_wait_for (with a selector that appears after panels render), and then browser_pdf_save. Schedule the prompt weekly and you have a fully automated reporting pipeline.

Recipe 5 — JS-heavy SPA scrape

Single-page apps that render everything client-side are murder for naive HTTP scrapers. Playwright MCP doesn’t care: the browser executes the JavaScript, the page settles, the accessibility tree fills in. Prompt: “Navigate to the product page, scroll until all variants load, extract every SKU and price.” The agent does the scroll-to-bottom loop with browser_evaluate (calling window.scrollTo), waits for new content with browser_wait_for, and returns structured JSON.

Recipe 6 — Screenshot regression on a key flow

Visual diff testing without a SaaS. Run the agent through your critical user flow (sign-up, checkout, whatever) and call browser_take_screenshot at each step. Save the PNGs to a known location, diff them against last week’s versions, and surface any regression to the team. Pair with browser_resize to capture mobile, tablet, and desktop viewports in the same run.

Recipe 7 — Generate Playwright tests from a manual run

The pattern Microsoft pushed in their own demo videos: let the agent run your flow once, then ask it to write the Playwright test for it. Prompt: “Walk through the checkout flow as a logged-in user, then write a Playwright test in TypeScript that does the same flow, using stable locators from browser_generate_locator.” The agent runs the flow with the core tools, generates locators along the way, and emits a ready-to-commit test file. Productivity multiplier on E2E test authoring.

Recipe 8 — Mock a flaky third-party API mid-flow

Sometimes the bug you’re chasing depends on a third-party response that’s slow or inconsistent. With --caps=network enabled, the agent can install a route handler before the page even loads. Prompt: “Before navigating, mock all requests to api.stripe.com to return this canned JSON. Then run the checkout flow.” The agent calls browser_route with a URL pattern and a stub response, then proceeds with the flow. Stripe never gets a real call; your test runs deterministically.

Headed vs headless mode

Default is headed — Playwright MCP launches a real browser window you can watch. That’s the right setting while you’re developing prompts, debugging a flaky flow, or demoing the agent to someone. You see what the agent sees, you can interrupt by clicking the window yourself, and screenshot calls capture the visible state.

Headless is the production mode. Append --headless to the install command (claude mcp add playwright npx @playwright/mcp@latest -- --headless) and the browser runs invisibly. CI, scheduled jobs, server-side agents — everywhere a window would just confuse the host machine. The tradeoff is debugging: when headless runs fail, you need screenshots, traces, or video to see what went wrong, because there’s no live window to watch.

A pragmatic pattern: register two MCP servers, named playwright-headed and playwright-headless, with the same package and different flags. Prompts that say “use the headed version so I can watch” target the first; production agent runs that say nothing default to the headless one. The agent picks based on tool naming.

Two more flags worth knowing in the same neighbourhood. --viewport-size=1280x720 fixes the browser viewport size (important for consistent screenshots). --device="iPhone 15" emulates a specific device profile, including viewport, user agent, and touch-event behaviour. Pair --device with headless for mobile-flow testing in CI.

Troubleshooting

When to switch — Playwright MCP vs Chrome DevTools MCP vs Puppeteer

Playwright MCP is the right default for browser-driving agents. It’s not the right tool for every adjacent job. The clearest decisions:

• You want performance auditing, Lighthouse scores, or DevTools-protocol-level inspection: use Chrome DevTools MCP. It exposes CDP primitives that Playwright wraps away, so you can throttle CPU, profile JS, and drive the Performance panel from agent prompts.
• You want only Chromium and a simpler API surface: a Puppeteer-based MCP server works. Puppeteer is a thinner wrapper. The trade-off is no Firefox / WebKit, fewer capabilities, and a smaller maintainer base behind it.
• You want big-scale crawling and content extraction (not interactive automation): Firecrawl, Anycrawl, and Crawlee are purpose-built for that. See our Firecrawl vs Anycrawl vs Crawlee vs Playwright for the matrix.
• You only need vision-based computer-use: Anthropic’s Computer Use or the vision-only MCP servers fit. They trade determinism for the ability to work on canvas-rendered apps without any DOM hooks.

The single most-requested comparison is Playwright vs Chrome DevTools — we wrote it as a standalone post: Chrome DevTools MCP vs Playwright MCP (2026). Short version: Playwright wins on cross-browser coverage and accessibility-tree determinism; Chrome DevTools wins on performance auditing and any task tied to the DevTools Protocol. If you’re still deciding which to install, that’s the head-to-head to read.

One last note on Puppeteer: Microsoft hires most of the original Puppeteer team, and Playwright is the spiritual successor. New features land in Playwright first; Puppeteer maintenance is steady but no longer the cutting edge. For new projects, Playwright MCP is the safer bet.

FAQ

Sources

• Playwright MCP repository & README: github.com/microsoft/playwright-mcp (Apache-2.0, maintained by Microsoft)
• NPM package: @playwright/mcp on npmjs.com
• Playwright project site: playwright.dev
• Official Playwright YouTube channel (live demos, release notes): youtube.com/@Playwrightdev
• Model Context Protocol spec: modelcontextprotocol.io