Playwright MCP is an MCP server that lets an AI client operate Playwright through structured accessibility snapshots. Install Node.js 20 or newer, add npx @playwright/mcp@latest to your MCP client, and the model can navigate pages, fill forms, click controls, manage tabs, and run browser workflows without a vision model. This guide covers setup, browser connections, profiles, security, advanced scripts, and troubleshooting.
What Playwright MCP does
Playwright MCP is a Model Context Protocol server built on Playwright. Instead of asking an AI model to interpret pixels, it returns an accessibility snapshot containing roles, labels, visible text, and element references. The model identifies a target such as a textbox or button, then calls an action with that reference.
A typical interaction looks like this: the server opens a page, returns a snapshot with a heading, textbox, checkbox, and list item, and assigns references such as e5 or e10. The assistant then navigates, clicks, types, fills forms, hovers, drags, presses keys, handles dialogs, switches tabs, or requests a screenshot using those references. This representation is usually more deterministic than guessing coordinates from an image and does not require a vision model.
What it is not
Playwright MCP is not a hosted browser service or a complete agent by itself. You supply an MCP-compatible client such as VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, or another client. The client sends tool calls to a local or remote Playwright MCP process, which controls a browser.
#1 Best Overall
- Compact Mouse: With a comfortable and contoured shape, this Logitech ambidextrous wireless mouse feels great in either right or left hand and is far superior to a touchpad
- Durable and Reliable: This USB wireless mouse features a line-by-line scroll wheel, up to 1 year of battery life (2) thanks to a smart sleep mode function, and comes with the included AA battery
- Universal Compatibility: Your Logitech mouse works with your Windows PC, Mac, or laptop, so no matter what type of computer you own today or buy tomorrow your mouse will be compatible
- Plug and Play Simplicity: Just plug in the tiny nano USB receiver and start working in seconds with a strong, reliable connection to your wireless computer mouse up to 33 feet / 10 m (5)
- Better than touchpad: Get more done by adding M185 to your laptop; according to a recent study, laptop users who chose this mouse over a touchpad were 50% more productive (3) and worked 30% faster (4)
Prerequisites and installation
- Node.js 20 or newer. Check with
node --version. - An MCP client that can launch a server from a command and arguments.
- Network access to the sites you want to automate.
The standard package is downloaded with npx; the browser binary is downloaded automatically on first use.
- Install or update Node.js to version 20 or newer.
- Open your MCP client’s server configuration.
- Add a server named
playwrightwith the command and arguments below. - Restart or reload the MCP client, then ask it to navigate to a test page.
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}The first launch may take longer while Playwright downloads its browser. Keep the client open until the server reports that it is ready.
Your first automation
Use a simple page such as TodoMVC for the initial test. Ask your assistant to navigate to the page, inspect the accessibility snapshot, and add a task. A robust request names the outcome rather than prescribing coordinates:
Open the TodoMVC demo, inspect the accessibility snapshot, type “Buy milk” into the textbox, and verify that the new item appears in the list.The assistant should first obtain a fresh snapshot, find the textbox reference, type into it, and verify the resulting list item. References are tied to the current page state; after navigation, a major DOM update, or a dialog, request another snapshot instead of reusing an old reference.
Actions exposed through MCP
- Navigate to a URL and go back or forward.
- Click, type, fill a form field, press keyboard keys, hover, and drag and drop.
- Handle JavaScript dialogs such as alerts and confirmations.
- Open, close, and switch between tabs or pages.
- Wait for a selector, a delay, or network idle.
- Take screenshots when a visual artifact is useful.
- Run direct Playwright code for flows that do not fit individual tool calls.
Selecting a browser engine
Playwright MCP documents Chrome/Chromium, Firefox, WebKit, and Microsoft Edge. Pass a browser flag in the server arguments when you need a specific engine.
| Engine | Argument | Use it when |
|---|---|---|
| Chrome/Chromium | --browser=chrome |
You need the default Chromium behavior or a Chrome channel. |
| Firefox | --browser=firefox |
You are checking Firefox-specific rendering or behavior. |
| WebKit | --browser=webkit |
You want WebKit coverage similar to Safari’s engine. |
| Microsoft Edge | --browser=msedge |
Your workflow depends on the Edge channel. |
For example, configure Firefox by changing the arguments to:
Rank #2
- The next-generation optical HERO sensor delivers incredible performance and up to 10x the power efficiency over previous generations, with 400 IPS precision and up to 12,000 DPI sensitivity
- Ultra-fast LIGHTSPEED wireless technology gives you a lag-free gaming experience, delivering incredible responsiveness and reliability with 1 ms report rate for competition-level performance
- G305 wireless mouse boasts an incredible 250 hours of continuous gameplay on just 1 AA battery; switch to Endurance mode via Logitech G HUB software and extend battery life up to 9 months
- Wireless does not have to mean heavy, G305 lightweight mouse provides high maneuverability coming in at only 3.4 oz thanks to efficient lightweight mechanical design and ultra-efficient battery usage
- The durable, compact design with built-in nano receiver storage makes G305 not just a great portable desktop mouse, but also a great laptop travel companion, use with a gaming laptop and play anywhere
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--browser=firefox"]
}
}
}Use one browser setting per server entry. If you need parallel workflows in different engines, create separate entries with distinct names and profiles.
Connect to an existing browser
You do not have to start a disposable browser for every task. Playwright MCP supports several connection modes.
Recommended Free Tools
Attach to a running Chrome or Edge channel
Use a browser channel when you want the locally installed Chrome or Edge application, including its normal rendering behavior. This is convenient for headed, interactive work on a developer workstation.
Connect through Chrome DevTools Protocol
A Chromium-based browser can expose a CDP endpoint such as http://localhost:9222. MCP can connect to Chrome or Chromium, Edge, Electron applications, and cloud browser services through CDP. Start the browser with remote debugging enabled, then configure the MCP server with the endpoint supported by your client and server version.
Connect to a Playwright server endpoint
If another process already runs a Playwright browser server, point MCP at its remote endpoint. This separates the MCP client from the browser host and is useful for CI workers or remote infrastructure.
Use extension mode
Extension mode connects to existing Chrome or Edge tabs. It can reuse a logged-in session, cookies, installed extensions, SSO state, and 2FA context. Because it attaches to real tabs, confirm that the assistant is operating in the intended window before allowing actions that submit forms or change data.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- Compact Mouse: With a comfortable and contoured shape, this Logitech ambidextrous wireless mouse feels great in either right or left hand and is far superior to a touchpad
- Durable and Reliable: This USB wireless mouse features a line-by-line scroll wheel, up to 1 year of battery life (2) thanks to a smart sleep mode function, and comes with the included AA battery
- Universal Compatibility: Your Logitech mouse works with your Windows PC, Mac, or laptop, so no matter what type of computer you own today or buy tomorrow your mouse will be compatible
- Plug and Play Simplicity: Just plug in the tiny nano USB receiver and start working in seconds with a strong, reliable connection to your wireless computer mouse up to 33 feet / 10 m (5)
- Better than touchpad: Get more done by adding M185 to your laptop; according to a recent study, laptop users who chose this mouse over a touchpad were 50% more productive (3) and worked 30% faster (4)
Profiles, authentication, and isolation
Persistent mode is the default. Playwright MCP stores a profile so cookies and login state survive between sessions. That makes repeatable work practical: log in once, then let the assistant continue from the authenticated state.
| Mode | State behavior | Best fit |
|---|---|---|
| Persistent profile | Cookies and local state are retained. | Recurring tasks and development accounts. |
| Isolated profile | Each session starts clean. | Tests that must not inherit personal data. |
| Custom user-data directory | Persistent state is stored at a directory you choose. | Separate workspaces, CI caches, or team-managed profiles. |
| Extension attachment | Uses the already running browser tabs and extensions. | SSO, 2FA, and sessions that cannot be recreated by a script. |
Keep personal and production credentials out of a shared profile. For reproducible tests, prefer an isolated profile and seed only the account data the workflow needs. For a custom location, provide --user-data-dir in the server arguments and restrict filesystem permissions to the account running MCP.
Direct Playwright code for complex flows
Individual MCP actions are ideal for ordinary navigation and forms. For loops, conditional logic, network mocking, or multi-step extraction, the server exposes browser_run_code_unsafe. It executes arbitrary JavaScript in the Playwright server process.
await page.goto('https://example.com');
const titles = await page.locator('h2').allTextContents();
return titles;This capability is RCE-equivalent. Only enable it for trusted MCP clients, and do not connect an untrusted model or remote client to a server that can execute arbitrary code. Run the process under a least-privileged account, isolate credentials, and avoid mounting sensitive directories into the environment.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsReliable automation patterns
Refresh references after state changes
Element references describe the current accessibility snapshot. After navigation, opening a menu, submitting a form, or loading dynamic content, obtain a new snapshot and select the new reference.
Wait for a condition, not an arbitrary sleep
Prefer waiting for a selector, a known text result, or network idle. A fixed delay can be too short on a slow run and unnecessarily long on a fast one. Use a delay only when a site has a documented timing requirement or an animation must complete.
Rank #4
- Computer mouse for easily navigating a computer interface; click, scroll, and more
- USB-A wired connection; if existing device only supports USB-C, an additional adapter will be required
- High-definition (1000 dpi) optical tracking ensures responsive cursor control for precise tracking and easy text selection
- 3 buttons offer effortless fingertip control
- Plug-and-go ready for instant use
Make destructive actions explicit
Ask the agent to summarize the target account, record, or amount immediately before a delete, purchase, permission change, or message send. Require a confirmation step in your client workflow rather than allowing an inferred click to commit an irreversible action.
Control downloads and sensitive output
Do not let an automated session download arbitrary files into a directory containing secrets. Use a dedicated workspace, inspect filenames and MIME types, and redact credentials before returning page text to a model.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Performance and deployment considerations
- Headless versus headed: Headless is generally easier for CI; headed mode helps debug focus, popups, and extension behavior.
- Browser startup: Reuse a persistent browser or remote endpoint for many short tasks instead of paying startup cost for every action.
- Parallelism: Give concurrent jobs separate profiles or contexts so cookies, local storage, and tabs cannot leak between tasks.
- Network conditions: Increase waits for slow staging systems and make navigation timeouts explicit in the client or script.
- Observability: Capture the accessibility snapshot and relevant console or network diagnostics when a run fails; a screenshot alone may not reveal why a control was unavailable.
- Remote browsers: A CDP endpoint can be hosted on another machine or by a cloud browser service. Protect that endpoint with network controls and authentication.
Playwright MCP’s documentation does not provide a universal reliability or speed figure. Actual throughput depends on the browser engine, page weight, network, model latency, and whether a local or remote browser is used.
Troubleshooting common failures
| Symptom | Likely cause | Fix |
|---|---|---|
npx or package not found |
Node.js is missing, older than 20, or the client cannot find your PATH. | Install Node.js 20+, verify node --version and npx --version, then restart the MCP client. |
| Browser download never completes | Firewall, proxy, or restricted network access. | Allow the Playwright download host through the network or preinstall browsers in the environment, then relaunch. |
| No tools appear in the client | Malformed JSON or the client has not reloaded its configuration. | Validate commas and quotes, confirm the server name, and fully restart the client. |
| “Element not found” after a snapshot | The page changed and the reference is stale, or the control is inside a different tab or frame. | Request a fresh snapshot, verify the active tab, and wait for the expected selector or text. |
| Login disappears between runs | An isolated profile is being used, the profile directory changed, or cookies were cleared. | Use persistent mode or a stable --user-data-dir; use extension mode when the existing browser session is required. |
| CDP connection refused | The browser was not started with remote debugging, the port is wrong, or a firewall blocks it. | Start the correct browser channel with CDP enabled, verify the endpoint locally, and restrict access to trusted hosts. |
| Unsafe code is blocked | The client or server intentionally disables browser_run_code_unsafe. |
Use normal MCP actions, or enable direct code only in a trusted, isolated environment. |
| Automation works locally but fails in CI | Missing browser binaries, different fonts, permissions, display settings, or network policy. | Install browsers during the CI image build, use headless mode, pin profile directories, and capture logs plus snapshots on failure. |
When to use Playwright MCP
Choose Playwright MCP when an AI agent must reason about page structure and then take browser actions: support triage, data-entry assistants, QA checks, authenticated workflows, and exploratory testing. Accessibility snapshots make the interaction inspectable and reduce dependence on visual models.
Use direct Playwright scripts when you need deterministic test suites, extensive fixtures, tracing, video, network mocking, or code-reviewed business logic. MCP is an interface for an agent; it does not replace conventional tests for critical paths.
Or skip the browser setup
If you only need a clean image or PDF of a URL, ScreenshotNeo provides a single HTTP request instead of a local browser and MCP configuration. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.
Read the parameter reference in the ScreenshotNeo documentation. The same endpoint supports full-page and element captures, device presets, retina scale, dark mode, PDFs, custom CSS and JavaScript, clicks, waits, blocking rules, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous webhooks, bulk requests, usage reporting, and an OpenAPI specification.
Best Value
- 【Plug and Play for Home/Office/School】The wireless computer mouse features 2.4GHz connectivity, delivering a stable, interference-free connection up to 32ft. Designed for 𝐦𝐞𝐝𝐢𝐮𝐦 𝐭𝐨 𝐥𝐚𝐫𝐠𝐞 𝐬𝐢𝐳𝐞𝐝 𝐡𝐚𝐧𝐝𝐬, it ensures comfortable use all day. Simply plug in the USB-A receiver for instant pairing—no drivers needed. 📌📌 If the mouse isn’t suitable, place the USB receiver in the battery compartment and return both.
- 【3 Levels Adjustable DPI】This travel USB mouse offers 3 adjustable DPI settings (800, 1200, 1600), allowing you to customize sensitivity for precise design work. Effortlessly switch to match your task and elevate your productivity. 📌 Please remove the film at the bottom of the mouse before use.
- 【Effortless Browsing】Equipped with forward and backward buttons, this computer mice streamlines your workflow, making it easy to navigate through web pages and files with a simple click. 📌Side button does not work on Mac.
- 【Visible Indicator Light】 The pc mouse features a visual indicator for DPI levels and low battery alerts. The red light flashes once for 800 DPI, twice for 1200 DPI, and three times for 1600 DPI. When the battery level is below 10%, the light flashes red until the mouse is completely out of power.
- 【Click to Wake】With smart sleep mode, it saves power by standby after 10 inactive minutes, just 2-3 clicks to wake. This efficient design delivers 3x longer battery life than motion-wake mice. Engineered for durability, its buttons and scroll wheel are tested for 10 million clicks, ensuring long-term reliability and consistent performance.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
ScreenshotNeo includes an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan, and yearly billing gives two months free.
Create a free ScreenshotNeo account to get 1,000 screenshots a month without adding a card.
FAQ
Frequently Asked Questions
Can Playwright MCP automate a site that requires an existing browser extension?
Yes. Use extension mode to attach to an existing Chrome or Edge tab and reuse its installed extensions, cookies, SSO state, and 2FA session.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Does Playwright MCP require a vision-capable AI model?
No. Its primary interaction path uses structured accessibility snapshots and element references. Screenshots remain available when visual inspection is useful.
Is a persistent profile appropriate for shared production credentials?
No. Persistent profiles retain cookies and login state, so keep them isolated per account and use least-privileged credentials. Use an isolated profile for clean, repeatable tests.
Can a remote browser be used instead of a local one?
Yes. MCP can connect through a CDP endpoint or a Playwright server endpoint, including endpoints hosted by cloud browser services. Secure the endpoint and limit trusted clients.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
