Playwright MCP: Setup, Browser Tests, and Limits

Give Claude Code, Codex, Cursor, or VS Code a real browser. Exact setup, practical tests, a worked checkout failure, and the safety limits.

Published Updated

Playwright MCP: Setup, Browser Tests, and Limits

Playwright MCP connects your coding agent to a real browser so it can navigate pages, fill forms, and inspect failures through structured accessibility snapshots. Install it with npx @playwright/mcp@latest through your MCP client; Playwright's current setup guide calls for Node.js 20 or newer. Use it for exploratory checks, then turn important findings into reviewed, repeatable tests.

For a client that accepts the README's standard JSON, copy this server entry into its MCP configuration:

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

The Microsoft Playwright MCP README supplies that configuration. Codex uses TOML instead; the client-specific commands below show where to start. For a founder, the useful outcome is a checkout, signup page, or lead form checked before customers reach it. Start with an anonymous staging flow and a precise definition of success.

A Short Browser Test to Give Your Agent

Ask your connected agent:

Open https://playwright.dev/ with Playwright MCP. Take a page snapshot, follow the Testing documentation link, and confirm the destination contains the Installing Playwright heading. Report the observed URL and heading, or the failing step. Close the browser when finished.

The intended sequence is browser_navigate, browser_snapshot, browser_click using the link's current target, then another snapshot to inspect the destination. With --caps=testing enabled, the agent can use browser_verify_element_visible with role: "heading" and accessibleName: "Installing Playwright". This is an example to run, not a test result claimed here. A completed click is not a pass: the destination heading is the success condition. The prompt follows the links on Playwright's current homepage.

What Playwright MCP Actually Does

Your agent gets browser controls and a structured description of the page. MCP, short for Model Context Protocol, is the connection that lets the agent call those tools. The server carries out the browser actions; the agent decides which action to request next.

Think of an accessibility snapshot as a building directory: it identifies rooms and doors by their purpose and name. A page snapshot similarly describes buttons, links, text fields, and their accessible names. The agent can select a target from that structure instead of guessing where to click in a picture. The default workflow does not require a vision model. Microsoft's overview

Architectural diagram showing an agent sending actions through the MCP server to a browser, with a page snapshot returning to the agent.
The agent chooses an action, Playwright carries it out, and the page structure informs the next decision. The return path is simplified here.

There is a choice to make before installing. Microsoft now points coding-agent users toward Playwright CLI with skills as another approach, while describing MCP as useful for persistent browser state and repeated inspection of page structure. Choose MCP when that continuing interaction fits your workflow; compare the CLI route if your agent already works comfortably through shell commands. Neither choice proves that a customer journey passed. Microsoft's MCP and CLI comparison

For the interface tradeoff, see MCP vs CLI. For the wider tool stack, see our best MCP servers for 2026.

Add It to Claude Code, Codex, Cursor, or VS Code

Use Node.js 20 or newer and a client that supports MCP. The repository README still says 18+, but the current Playwright MCP setup page specifies 20+; use the stricter requirement for a new installation. The commands and configuration below reproduce Microsoft's README examples. Pick your client; these are alternative installations, not a sequence to run across every editor. Playwright's MCP setup guide

Claude Code

Run this exact command:

claude mcp add playwright npx @playwright/mcp@latest

Codex

Run this exact command:

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

Alternatively, add the following to ~/.codex/config.toml:

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

Cursor

Follow the README's manual route: Cursor Settings -> MCP -> Add new MCP Server. Choose a name, select the command type, and enter:

npx @playwright/mcp@latest

Use Edit to inspect the configuration or add arguments. The README also provides an Install in Cursor button.

VS Code

Use the VS Code CLI command exactly as given:

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

The server becomes available to your GitHub Copilot agent in VS Code. Microsoft's README also links to installation buttons and the VS Code MCP setup guide.

The standard JSON at the top is the README's shared configuration; use the client-specific route to place it. For choosing the surrounding agent, see AI coding agents with browser testing.

Since the original October 12, 2026 guide, Microsoft has released v0.0.84 on October 31 and v0.0.85 on November 9. Verified against Microsoft's live README, release notes, and Playwright docs on November 12, 2026, the current setup commands remain the same; the useful changes concern cross-page evidence, locator matching, and extension control. Restart the client to pick up the current package through @latest, or pin @playwright/mcp@0.0.85 when you need a fixed dependency. Microsoft's release notes

Choose the Browser and How the Agent Sees It

Start with a visible browser, an isolated profile, and snapshots. Add options to the server's argument list after @playwright/mcp@latest. These options come from Microsoft's configuration reference.

DecisionREADME optionWhat it changes
Show the browser windowHeaded is the default; add --headless to hide itHeadless controls the window, not whether the agent can interact with the page.
Choose a browser--browser accepts chrome, firefox, webkit, msedgeThese are the CLI values. The JSON browserName field separately uses chromium, firefox, or webkit.
Start without saved browser state--isolatedKeeps the profile in memory; closing the browser discards that session's state.
Control response snapshots--snapshot-mode accepts full or none; default fullControls snapshots returned with responses. It is separate from coordinate interaction.
Add coordinate interaction--caps=visionAdds mouse tools that act on coordinates.
Control returned images--image-responses accepts allow, omit, or only; default allowControls image responses sent to the client.
Test another layout--device or --viewport-sizeSelects device emulation or a viewport size.
Keep evidence--output-dir, --save-sessionSets the directory for automatically named outputs and enables saving the MCP session. Explicit filenames resolve against the workspace root.
Adjust waiting--timeout-action, --timeout-navigationConfigures action and navigation timeouts. Increasing them does not fix a broken flow.

Snapshot versus vision is about the interaction method. In the default flow, use browser_snapshot to identify targets. browser_take_screenshot captures visual evidence, but taking a screenshot does not itself enable coordinate clicks. With --caps=vision, the README lists browser_mouse_click_xy, browser_mouse_down, browser_mouse_drag_xy, browser_mouse_move_xy, browser_mouse_up, and browser_mouse_wheel. Your client and model must be able to use the returned images for visual reasoning. Tool reference

In v0.0.85, snapshots keep identifying container names and recognize labels on form-associated custom elements. The release also reverts v0.0.84's inert/modal snapshot filtering: appearing in a snapshot does not mean an element is actionable. If hidden duplicates confuse targeting, browser.contextOptions.locateOnlyVisible: true in the server config restricts locators to visible elements; it is off by default.

My starting choice is snapshots for ordinary forms and navigation. Use visual inspection when appearance matters or the page structure cannot describe the control adequately. An accessibility snapshot is useful evidence about structure; it cannot establish that the page looks right.

The Tools That Matter During a Browser Check

The core tool set covers navigation, interaction, and evidence collection. This table groups the README's core automation and tab tools by the job you give the agent.

JobTool names
Open and manage pagesbrowser_navigate, browser_navigate_back, browser_tabs, browser_close
Read the page structurebrowser_snapshot, browser_find
Click and movebrowser_click, browser_hover, browser_drag
Enter databrowser_fill_form, browser_type, browser_select_option, browser_press_key
Handle files and dialogsbrowser_file_upload, browser_drop, browser_handle_dialog
Change presentationbrowser_resize, browser_emulate_media
Wait for a statebrowser_wait_for
Collect evidencebrowser_take_screenshot, browser_console_messages, browser_network_requests, browser_network_request
Execute codebrowser_evaluate, browser_run_code_unsafe

Snapshot-based actions use a target reference from the page snapshot or a unique selector. A selector is a way to identify a page element. Refresh the snapshot after a meaningful page change instead of assuming an earlier target still applies.

Additional capabilities are opt-in. The options table lists vision, pdf, and devtools; the tool sections also explicitly document config, network, storage, and testing:

  • PDF: --caps=pdf adds browser_pdf_save.
  • Debugging evidence: --caps=devtools includes tracing, video, action recording, annotations, highlighting, and resuming paused execution. For example, browser_start_tracing and browser_stop_tracing bracket a trace.
  • Assertions: --caps=testing adds browser_generate_locator, browser_verify_element_visible, browser_verify_list_visible, browser_verify_text_visible, and browser_verify_value. An assertion states what must be true.
  • Network simulation: --caps=network adds browser_network_state_set, browser_route, browser_route_list, and browser_unroute for offline behavior and mocked requests.
  • Storage: --caps=storage adds cookie, local-storage, and session-storage inspection and editing, plus browser_storage_state and browser_set_storage_state.
  • Resolved settings: --caps=config adds browser_get_config.

For longer journeys, v0.0.84 adds all: true to browser_network_requests, retaining up to 200 requests from earlier navigations with stable request indexes. Use it when a redirect would otherwise hide the request that explains a failure. browser_find also accepts maxResults to bound matching results, and browser_tabs with action: "new" accepts an isolatedContext name: matching names share cookies and storage, different names keep them separate.

Those are the README's documented groups, not a promise that every client exposes every tool immediately. If a tool is missing, compare the installed package's tool list and enabled capabilities with the README.

Three Business Jobs Worth Giving It

Prioritize journeys where failure blocks revenue or stops a customer from reaching you. The following are proposed workflows, not claims of measured savings.

Protect the Route to Checkout

A store developer could ask the agent to follow guest checkout on staging, confirm that the chosen item survives into the cart, fill synthetic shipping details, and stop before any real payment. The payoff is finding a purchase-blocking error before a customer does.

A second useful job for the same team is an error-recovery check: submit incomplete shipping data, confirm the error is understandable, correct it, and verify that the customer can continue. A happy path alone misses the customer who mistypes a field.

Check the Site After a Deploy

A founder shipping a landing-page change could have the agent open the deployment, follow the main call to action, and verify that it reaches the intended signup or contact page. Ask for page evidence and any relevant console or failed-request output.

An agency developer could then check a narrower viewport and repeat the navigation. This could reveal an obscured menu or unreachable button. Treat the screenshot as something to review, not an automatic visual-quality certificate.

Exercise Forms With Test Data

A SaaS developer could test an anonymous signup form's required fields, validation messages, and correction path in a local or staging environment. Stop before creating a real account, or use a test-only destination designed for submissions.

An operations developer could fill a long staging form from synthetic input, checking dropdowns, conditional fields, and a test file upload before submission to a mock endpoint. This helps expose field-mapping mistakes without sending customer records or triggering a real workflow.

Worked Example: A Guest Checkout That Cannot Reach Payment

Give the agent a bounded task and require evidence for its conclusion. This is an illustrative end-to-end example, with a deliberately assumed defect. It is not a report from testing a live store.

The example app has a guest cart, a shipping form, and a payment page. Its shipping form mistakenly sends the postal-code field as postal while the backend expects postalCode. Use an anonymous local or staging fixture with fake data and no real payment connection.

Give your agent this brief, replacing the bracketed URL with your own test fixture:

Use Playwright MCP to test guest checkout at [staging checkout URL]. Use an isolated browser session and synthetic guest details. Confirm that an item reaches the cart, required shipping fields reject empty input, and corrected shipping details allow progress to the payment page. Do not sign in, create an account, or place an order. If a step fails, stop that path and report the expected result, observed result, reproduction steps, relevant browser evidence, and anything not tested. Separate observations from suspected causes.

The isolation setting belongs in the server configuration as --isolated; putting it in the prompt alone does not configure the server.

  1. Open the fixture. Use browser_navigate, then browser_snapshot. Retain: The actual page and controls available.
  2. Build the cart. Use browser_click on the chosen item's control and open checkout. Retain: A snapshot confirming the item appears in the cart.
  3. Check required fields. Submit the empty shipping form. Retain: Visible validation messages, not just a successful click.
  4. Correct the input. Use browser_fill_form and browser_select_option where needed; click Continue. Retain: The corrected values and the resulting page state.
  5. Investigate the block. Capture browser_snapshot, browser_console_messages, and browser_network_requests; inspect the relevant request with browser_network_request. Retain: The shipping error and the request/response that help explain it.
  6. Report and close. Save browser_take_screenshot, write the finding, and call browser_close. Retain: An evidence-backed failure report with payment marked untested.

In this example, the request body contains postal and the response identifies the missing postalCode. That supports a mapping-error hypothesis. The developer should still inspect the form serialization and backend contract before declaring the root cause fixed.

Architectural checkout flow from cart to address, blocked before payment, with a branch to an evidence report.
A blocked shipping step becomes a specific report. The agent must mark the payment stage as unreached, rather than infer that checkout works.

Illustrative agent report:

Result: FAIL. Guest checkout cannot advance from shipping to payment with the supplied valid test address.

Passed: The chosen item appears in the cart. Empty required shipping fields show validation messages.

Reproduce: Open the fixture with an isolated profile, add the test item, open guest checkout, enter the fixture's valid shipping details, and select Continue.

Expected: The payment page becomes available.

Observed: The shipping form remains visible and reports a missing postal code. The shipping request contains postal; the response identifies missing postalCode.

Evidence to attach: The shipping-page screenshot, accessibility snapshot, and relevant request/response excerpt, with test data only.

Likely cause: A mismatch between the form's field mapping and the backend's expected property. Confirm in code.

Not tested: Payment entry, payment submission, order creation, or confirmation. The flow stopped before those stages.

The next step is to correct the mapping and rerun both the invalid-input and valid-input paths. After the behavior is confirmed, have the agent draft a Playwright regression test, review its assertions, and add it to your existing test runner. That last step is your engineering workflow; the MCP conversation alone is not a regression suite. Playwright Test's introduction describes the test runner; its assertion documentation explains the checks that wait for expected page states. For a framework choice, see Playwright vs Selenium.

Where It Breaks, and What the Browser Agent Can Reach

The weakest checks are the ones with a vague goal or an unsafe environment. “Check checkout” leaves the agent to invent success criteria. “Confirm that valid shipping details reach the payment page, without submitting payment” is reviewable.

Expect these practical limits:

  • Ambiguous page structure: Unnamed controls and canvas-heavy interfaces make the structural directory less useful. My recommendation is to fix accessible labels where you own the app, and use visual evidence where structure is insufficient.
  • Changing state: A rerender, popup, or delayed transition can invalidate the agent's next assumption. Inspect the resulting state and wait for the intended text or transition before continuing.
  • Profile collisions: A persistent profile can serve only one browser instance at a time. Microsoft recommends isolated sessions or distinct --user-data-dir values for concurrent clients sharing a workspace.
  • Environment mismatch: The README's Docker implementation supports headless Chromium only. Do not infer that every browser choice in the general CLI table works in that container.
  • Incomplete coverage: Reaching a page does not establish that every validation, browser, device, or backend outcome works. A screenshot also cannot prove that an order was correctly stored. These are limits of the proposed checking workflow.

The profile and Docker restrictions are documented in Microsoft's README.

Treat browser access as real access. Microsoft explicitly states that Playwright MCP is not a security boundary. The default profile persists browser state; the optional Chrome/Edge extension can connect to existing tabs and signed-in sessions. For the jobs here, use an isolated session without imported cookies or a connection to your everyday browser.

The agent can request pages reachable from the browser's environment. That can include development servers or internal services as well as public websites, depending on your network. Origin rules are not a substitute for network isolation: --allowed-origins and --blocked-origins do not constrain redirects and are explicitly not a security boundary. --allowed-hosts concerns the MCP server's incoming host checks, not a list of websites the browser may visit.

File access deserves the same care. The documented default restricts files to workspace roots and blocks file:// navigation, while --allow-unrestricted-file-access relaxes those rules. Microsoft describes the file checks as guardrails, not secure containment. More seriously, browser_run_code_unsafe executes JavaScript in the server process, with the reach of that process. Control that tool through client permissions and restrict the server environment. Configuration schema and tools

For extension users, v0.0.85 adds --background to avoid stealing focus and --no-tab-group to preserve existing tab groups. Both require extension 0.5.0 or later; background tabs can throttle timers and animation frames, so a less intrusive session may behave differently from a foreground check. Config file paths now resolve from that file's directory, while CLI and environment paths remain relative to the working directory. If a client stalls while answering workspace-root requests, --ignore-roots uses the server's working directory instead.

Screenshots, page text, console output, and request bodies can expose data to the agent. Use fake records and test-only endpoints. The newer --redact-url-params option can hide named URL query and fragment values in responses, but Microsoft calls it a convenience rather than a security feature. Stop before a real charge, message, account creation, or other consequential submission unless that specific action is deliberately authorized.

Playwright MCP, Chrome DevTools MCP, or Browserbase?

Choose according to the job and where the browser should run. These products overlap, but they are not interchangeable layers.

Playwright MCP provides structured-snapshot browser automation with browser selection and opt-in tool groups. Pick it to explore customer journeys and collect failure evidence across the supported browser choices.

Chrome DevTools MCP controls live Chrome with Puppeteer-based automation, performance traces, network inspection, screenshots, and console debugging. Its official browser support is Chrome and Chrome for Testing. Pick it when a Chrome performance or debugging problem makes DevTools evidence central.

Browserbase hosts browser sessions. Its Playwright quickstart creates a cloud session and connects through CDP, the Chrome DevTools Protocol, with live debugging and a session recording. Pick a hosted runtime when browser infrastructure needs to move off a developer's machine.

Microsoft also exposes --cdp-endpoint for connecting to a browser endpoint. That is why the interface your agent uses and the place your browser runs are separate decisions. Browserbase is not another name for Microsoft's server. Our best browsers for AI agents covers that broader choice.

Two Things Worth Building

Build around a repeatable acceptance checklist and a useful failure report. Installing the server alone does not supply test fixtures, assertions, or human review. For a wider testing stack, compare BrowserStack alternatives and AI code testing tools.

Strongest Opportunity: A Release Acceptance Service

A small agency could offer a review of agreed customer journeys after each client deployment. The smallest useful version takes a staging URL and acceptance checklist, runs the permitted anonymous paths, and produces a reviewed report with evidence and explicit coverage gaps. The client pays for someone owning the release check.

Validate a focused service with existing clients before investing in a broad software product.

The catch is maintenance: changing journeys, ambiguous assertions, and false alarms can consume the labor you hoped to save. The defensible part is a useful acceptance checklist and trustworthy triage, not installing the same public MCP server anyone else can install.

Second Opportunity: A Staging Form Checker

A web agency could build a checker that fills forms with synthetic values, exercises required-field errors, and confirms that a corrected submission reaches a mock destination. Start with the forms in sites the agency already maintains and a report a developer can reproduce.

Sell this as an addition to website maintenance, then validate repeat demand before building a separate product.

The catch is the receiving system. A successful-looking page does not prove a lead reached its destination. The MVP needs a test endpoint or another permitted way to verify receipt, alongside the browser evidence.

Questions You Will Have During Setup

Can I watch the agent use the browser?

Yes. Playwright MCP runs headed by default. Add --headless when you want it to run without a visible browser window.

Do I need a vision model?

Not for the default accessibility-snapshot workflow. Coordinate tools are an opt-in capability through --caps=vision; using them for visual reasoning also depends on your client and model's image support.

Can I test checkout or signup without signing in?

Yes, if your application exposes the relevant guest or anonymous flow. Use an isolated local or staging session and fake data. Stop at authentication or a real submission boundary; report that later steps were not tested.

Does a successful agent run replace my browser tests?

No. It establishes only what that run actually checked. Keep the evidence, turn important findings into reviewed tests, and run those tests through your normal regression process.

Your Monday move: pick the guest journey closest to revenue, write its expected result and stopping point, and ask your existing coding agent to check it on staging. Review the evidence with the developer who owns that flow before expanding the scope.

If you want a browser-checking workflow built around your release process, we build AI agents for business workflows.

Last Updated
Category
Build
Related Articles
Augment Code Review

Augment Code Review

Should your team pay for Augment Code? See how it finds cross-repository dependencies, where its index stops, and how shared usage affects the bill.Nov 21, 2026Build
Vercel Board

Vercel Board

Set up Vercel Board for two agents and a developer. Track a fix through review, choose channel permissions, and sync the thread with Slack or GitHub.Nov 20, 2026Build
Gemini API Tool Retrieval: How an Agent Loads a Schema on Demand

Gemini API Tool Retrieval: How an Agent Loads a Schema on Demand

Follow a refund from schema search to function call, choose server-side or client-side retrieval, and see when deferring Gemini tools costs more.Nov 20, 2026Build
Genie 4 API: How One Live World Session Works, and What It Costs

Genie 4 API: How One Live World Session Works, and What It Costs

Genie 4 opened on the Gemini API on Nov 19, 2026. How one live world session runs, in Google's own code, what a minute costs and where it stops.Nov 19, 2026Build
MAI Code 2 in GitHub Copilot

MAI Code 2 in GitHub Copilot

Choose MAI Code 2 or Flash by the scope of a fix. Check which Copilot plans include each model, where to find the picker and how organization policy works.Nov 19, 2026Build
GitLab Alternatives in 2026: Gitea, GitHub, Forgejo, Bitbucket, Azure DevOps, Codeberg and OneDev

GitLab Alternatives in 2026: Gitea, GitHub, Forgejo, Bitbucket, Azure DevOps, Codeberg and OneDev

Compare seven GitLab alternatives by hosting, CI capacity, registry, security and seat price. See what each importer moves and which pipelines need rewriting.Nov 19, 2026Build
Social Media API in 2026: Zernio, Ayrshare, Phyllo and the Native APIs

Social Media API in 2026: Zernio, Ayrshare, Phyllo and the Native APIs

Compare Zernio, Ayrshare, Phyllo and four native APIs for publishing and creator data. See how customers connect and which features need approval.Nov 18, 2026Build
AGENTS.md vs CLAUDE.md

AGENTS.md vs CLAUDE.md

Which file should your coding agents read? See how Claude Code, Codex, Cursor and Copilot load instructions and how one import keeps team rules in sync.Nov 18, 2026Build
Newsletter

One letter, every Sunday.Working systems, not hot takes.

Weekly. No spam. Unsubscribe anytime.