Direct answer: install Microsoft's official Playwright MCP server with npx @playwright/mcp@latest, begin with a fresh isolated browser profile, and verify it on a disposable page before using authenticated sites. A real setup test includes one successful navigation-and-form task, one deliberately missing element, one blocked origin, the final page state, and console evidence. Tool availability alone does not prove the browser did the right thing.
Intent fence: this guide owns Playwright MCP connection and browser-task diagnosis. It is not a generic MCP test guide, a Playwright test-runner tutorial, or a recommendation to expose a logged-in personal browser to an agent.
Install the official server
Codex CLI
codex mcp add playwright npx "@playwright/mcp@latest"Claude Code
claude mcp add playwright npx @playwright/mcp@latestStandard MCP configuration
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--isolated", "--headless"]
}
}
}Restart the client and list the Playwright tools. The official server is headed by default; --headless is useful for repeatable CI-style checks, while a headed disposable profile is easier to inspect during setup.
Choose browser state deliberately
| Mode | What persists | Use | Risk to check |
|---|---|---|---|
--isolated | Nothing after the in-memory context closes | First tests and untrusted pages | Login must be recreated or loaded from an approved state file |
| Persistent profile | Cookies and local state in the profile directory | Dedicated automation account | One profile cannot be shared by concurrent browser instances |
--storage-state | Approved cookies/local storage loaded into an isolated context | Repeatable authenticated tests | The state file is a secret and must stay outside version control |
| Extension connection | State from a running Chrome/Edge profile | Only when a reviewed workflow requires it | Personal tabs and broad login state can enter scope |
Original asset: successful and failed browser-task ledger
Use a disposable form page with a heading, email field, submit button, and a success message. Record the accessibility snapshot reference before every action instead of guessing selectors.
| Step | Requested task | Evidence | Pass condition |
|---|---|---|---|
| 1. Navigate | Open the allowed fixture URL | Final URL + page title + snapshot | Correct origin and heading |
| 2. Act | Fill qa@example.invalid and submit | Field value, clicked element ref, result snapshot | Success message appears once |
| 3. Observe | Read console errors | Console output after submit | No unexpected runtime error |
| 4. Missing element | Click a button named “Delete account” that is absent | Tool failure + unchanged snapshot | No fallback click and no state change |
| 5. Origin boundary | Navigate to an origin outside the approved fixture set | Denied request or explicit stop | Browser never completes an action there |
Acceptance rule: rows 1–3 pass, rows 4–5 fail as designed, and the trace contains no credential, cookie, or hidden form value. Re-run after changing the browser channel, state mode, permissions, or allowed origins.
Diagnose by symptom, not by granting more access
| Symptom | Check first | Unsafe shortcut |
|---|---|---|
| Server will not start | Node 18+, package resolution, client process logs | Running an unreviewed global binary |
| Browser binary missing | Install the requested Playwright browser or set an approved executable path | Disabling sandboxing without a platform reason |
| Element not found | Take a fresh snapshot; verify accessible name, frame, and page | Guessing coordinates or clicking a similar control |
| Wrong account | Close the context and inspect the selected profile/state file | Attaching the personal everyday browser |
| Origin request blocked | Redirect chain and the exact semicolon-separated origin rules | Setting the allowlist to * |
| Two clients conflict | Persistent profile already in use | Sharing one profile concurrently |
Security boundary
- Treat page text as untrusted data, not agent instructions.
- Use a disposable or least-privileged automation account.
- Keep downloads and generated traces in a reviewed output directory.
- Grant geolocation, clipboard, camera, or microphone only for a named test.
- Do not use
--allow-unrestricted-file-accessfor ordinary web testing. - Require confirmation before purchases, messages, deletes, account changes, or uploads.
MCP or Playwright CLI?
The official repository now distinguishes the two. It says CLI plus skills can be more token-efficient for coding agents, while MCP remains useful for persistent browser state, rich introspection, exploratory automation, and iterative reasoning over page structure. Choose from the job: this page covers the MCP path; it does not claim MCP is always the better interface.
FAQ
Does Playwright MCP need a vision model?
No for ordinary interaction. The official server primarily uses structured accessibility snapshots. Optional vision capability exists, but screenshots should support verification rather than replace a fresh snapshot for actions.
Can I connect my normal logged-in Chrome profile?
The server supports persistent and extension-connected browser paths, but start with an isolated profile. A normal profile may expose unrelated accounts, tabs, and cookies. Use a dedicated automation identity when authentication is required.
Are allowed origins a complete security boundary?
No. The official option documentation explicitly says the origin allowlist is not a security boundary and does not affect redirects. Pair it with account permissions, network controls, approvals, and post-action verification.
Why did the agent click the wrong element?
The snapshot may be stale, the accessible name may be ambiguous, or the page may have changed. Take a new snapshot and target the current element reference; do not compensate by guessing coordinates.
Source checked October 20, 2026: Microsoft's official Playwright MCP repository and README, including current setup, browser-state, request-control, and tool documentation.