Playwright MCP Setup: Isolate the Browser Before You Automate
Install Microsoft’s official Playwright MCP server with npx -y @playwright/mcp@latest, connect it to one MCP client, and begin with an isolated browser profile against a harmless target. Prove navigation, snapshots, clicks, typing, and form filling before adding persistent login state or broader network access.
Install Microsoft’s official Playwright MCP server with npx -y @playwright/mcp@latest, connect it to one MCP client, and begin with an isolated browser profile against a harmless target. Prove navigation, snapshots, clicks, typing, and form filling before adding persistent login state or broader network access.
Table of contents
- What Playwright MCP controls
- Choose persistent, isolated, or extension mode
- Install and connect one MCP client
- Prove navigation, snapshot, and form actions
- Contain sessions, origins, downloads, and code execution
- Fix browser, display, heartbeat, and profile failures
- FAQ
What Playwright MCP controls
Playwright MCP lets an LLM drive a real browser through Microsoft’s official Playwright-based MCP server. Install it with npx -y @playwright/mcp@latest, then use structured accessibility snapshots for browser actions instead of screenshots and a vision model. Read the official getting-started guide.
The server can navigate, click, type, fill forms, manage tabs, inspect network activity and console output, and evaluate code. Its default transport is local stdio, and the server itself requires no authentication. Node.js 18 or newer and an MCP-capable client are required.
| Setting | What to expect |
|---|---|
| Install | npx -y @playwright/mcp@latest |
| Transport | Local stdio by default |
| Authentication | None for the server itself |
| Browser | Playwright browsers download on demand |
| Clients | VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Goose, LM Studio, Codex, Gemini CLI, and others |
| Container | mcr.microsoft.com/playwright/mcp runs headless Chromium |
The MCPtrove Playwright MCP Server entry is a practical reference for package details, prerequisites, transport, and supported clients. By default, Playwright MCP launches a headed browser with a persistent profile, so login state can survive between sessions. The --headless, --isolated, --user-data-dir, and --browser options change that behavior. Supported browser choices include Chrome, Firefox, WebKit, and Microsoft Edge. See the configuration options.
Choose persistent, isolated, or extension mode
Choose isolated mode for initial setup and unknown targets, persistent mode for a trusted workflow that needs saved login state, and extension mode only when you intentionally need an existing browser context. Make the choice before testing so you know which session state the client is using.
An isolated profile separates first-run navigation and form tests from saved cookies, local storage, and previous tabs. Use it against a harmless target and confirm that the basic interaction loop works before introducing account state.
A persistent profile fits a trusted workflow that depends on a login surviving between sessions. Keep it dedicated to that workflow, and use --user-data-dir when you need to control where the profile is stored. A login in one profile should not be assumed to exist in another.
Extension mode is a deliberate context choice. Before clicking or submitting anything, confirm that the active browser context and session are the ones intended for automation.
| Situation | Start with |
|---|---|
| First setup or unfamiliar target | --isolated |
| Trusted workflow with reusable login | Persistent profile |
| Existing browser context required | Extension mode |
| Containerized execution | Docker image with headless Chromium |
| No graphical display | --headless |
The user-profile guidance explains how login persistence and isolated sessions affect browser state. Use it before moving from an isolated run to a persistent one.
Install and connect one MCP client
Install Node.js 18 or newer, choose one MCP-capable client, and add Playwright MCP as a local stdio server. Start with the standard command and confirm that the client exposes the server tools before changing transport or capability settings.
npx -y @playwright/mcp@latest
The command uses the published @playwright/mcp npm package. Playwright browsers download on demand, so the first launch may include browser setup before navigation tools become available.
Start with one client and one server process so failures can be isolated to Node.js, the connection, the browser, or the target.
Playwright MCP also supports SSE and standalone HTTP transports through --port, but local stdio is the direct starting point for a local client. Add another transport only when the client or deployment requires it.
The browser-automation capability guide helps map browser actions to a client’s tool panel. For the relationship between clients, servers, and transports, see the MCP architecture documentation.
Prove navigation, snapshot, and form actions
Prove the smallest useful loop in order: navigate to a harmless target, inspect its accessibility snapshot, click a non-destructive control, type into a test field, and fill a form without sensitive data. This confirms that the client, server, browser, and target work together.
Use this sequence:
- Start Playwright MCP with the selected profile mode.
- Navigate to a harmless page you are authorized to use.
- Request or inspect the page’s structured accessibility snapshot.
- Identify a visible link or control and click it.
- Open a harmless test form.
- Type into one field and use form filling for another.
- Confirm the resulting page state through another snapshot.
- Stop before credentials, payments, or irreversible submissions.
Snapshots are central because they provide structured page information without requiring screenshot interpretation. The always-available core tools include navigation, snapshots, click and typing actions, tabs, network inspection, console inspection, and evaluation.
Keep the first pass read-oriented. A successful click proves that the interaction path works; it does not establish that a target is appropriate for broader automation. Record whether the browser was headed or headless and which profile was active.
If the page behaves differently from its visible layout, inspect the accessibility snapshot and console output first. The optional vision capability adds coordinate-based mouse tools, but structured output should be the first diagnostic reference.
Contain sessions, origins, downloads, and code execution
Treat Playwright MCP as an automation channel, not a security boundary. Use trusted targets, isolate browser state, and review actions that can submit data, reach internal sites, download content, or execute code.
Playwright MCP can drive a real browser to any URL and submit forms using whatever session state the browser has. Therefore, the server’s lack of authentication does not mean that the browser session has no authority. Read the MCP security best practices.
| Area | Containment approach |
|---|---|
| Sessions | Start with an isolated profile; add persistent state only for a trusted workflow |
| Origins | Use authorized, harmless targets first; internal sites may be reachable |
| Downloads | Review the target and resulting file as side effects |
| Form submission | Use test data and stop before sensitive or irreversible actions |
| Code execution | Keep evaluate use narrow and intentional |
| Extra capabilities | Add only the --caps groups the workflow needs |
The core tools are always enabled. Optional capability groups include vision for coordinate-based mouse tools, storage for cookie and web-storage operations, devtools for tracing, video, and highlighting, and pdf for PDF export.
Add persistent login state or wider network access only after the read-click-fill loop is proven. Keep browser profiles, target origins, downloaded outputs, and client permissions within the workflow’s intended scope.
Fix browser, display, heartbeat, and profile failures
Check failures in order: Node.js and browser availability, display mode, client heartbeat or transport, then profile selection. Change one variable at a time and preserve the last known-good command. Use the MCP debugging guide.
| Symptom | Check first | Practical next step |
|---|---|---|
| Server does not start | Node.js version and client configuration | Confirm Node.js 18 or newer and the standard command |
| Browser does not appear | Headed versus headless mode | Use --headless without a graphical display |
| Container launch fails | Image and display assumptions | Use mcr.microsoft.com/playwright/mcp for headless Chromium |
| Wrong browser opens | Browser selection | Set --browser to Chrome, Firefox, WebKit, or Microsoft Edge |
| Login is missing | Profile mode or directory | Check --isolated and --user-data-dir |
| Client loses the server | Transport and process output | Check the stdio connection and client logs |
| Page action is unclear | Snapshot, console, and network state | Inspect structured output before adding capabilities |
A headed browser is the default, so a missing window does not necessarily mean that the server failed. In a container or display-free environment, headless mode is expected, and the published Docker image runs headless Chromium.
Profile failures are often profile-selection failures rather than login failures. An isolated run and a persistent run intentionally use different browser state, so verify the active mode and directory before repeating authentication.
If the client requires another transport, Playwright MCP supports SSE and standalone HTTP through --port. Consult the MCP configuration options before changing supported flags. For a practical configuration check, use MCPtrove’s Config Doctor, then compare the result with the documented setup. The guide to testing an MCP server provides a further workflow reference.