How it works
Playwright is Microsoft’s browser automation framework. Playwright MCP wraps it as an MCP server, so an AI agent gets tools such as “navigate”, “click”, “type” and “take snapshot”.
The key design choice: it does not show the model pixels. It gives the model the page’s accessibility tree, a structured list of buttons, links, fields and text, the same structure screen readers use. The agent reads that with browser_snapshot, picks an element and acts on it. That works with any text model and is more reliable than guessing coordinates on a screenshot. When an element is missing from the tree, the optional --caps=vision adds coordinate-based mouse tools. browser_take_screenshot exists too, but only for looking.
Setting it up
| Step | What to do |
|---|---|
| Requirement | Node.js 18 or newer |
| Claude Code | claude mcp add playwright npx @playwright/mcp@latest |
| Other clients | Add an mcpServers entry that runs npx @playwright/mcp@latest; the README lists VS Code, Cursor, Codex, Copilot CLI, Gemini CLI, Claude Desktop, Grok, Windsurf and more |
| Headless | --headless (the default is a visible browser) |
| Clean state | --isolated keeps the profile in memory only |
| Specific login state | --storage-state loads cookies and local storage into an isolated context |
| Your own browser | --extension with the Playwright Extension connects to a running Chrome or Edge |
Two defaults to know. The browser profile is persistent, stored under ms-playwright in your cache directory, so logins survive between sessions. And only one browser can use a profile at a time, so parallel agents need --isolated or separate --user-data-dir values.
Playwright’s own documentation describes the same server from the user’s side: it works on “structured accessibility snapshots”, so “no vision models required”, and the model clicks elements by reference (such as ref=e5) rather than by pixel. Screenshots exist, but for visual checks, not for driving the page.
MCP or CLI: Microsoft’s own advice
The README is candid: coding agents increasingly prefer CLI-based workflows with skills, because MCP loads large tool schemas and accessibility trees into the context. Microsoft recommends MCP for loops that need persistent browser state, rich page inspection, or long-running autonomous work, where keeping the browser context matters more than token cost.
In practice:
- Exploring a bug, checking a flow, debugging a form: Playwright MCP is a good fit. The agent sees the live page and can try things.
- Regression tests that must run on every commit: write Playwright tests and run them in CI. The agent can help write them; it should not be the test.
- Short, repeated tasks in a coding agent: consider the CLI and skills route the README mentions, to save context.
The common misunderstanding: safety
Because it is from Microsoft, teams assume Playwright MCP is safe by default. The README says plainly that it is not a security boundary. Some specifics:
--allowed-originsand--blocked-originslimit browser requests, but the README says they are not a security boundary and do not cover redirects.browser_run_code_unsaferuns arbitrary JavaScript in the server process; the README calls it equivalent to remote code execution.- The
secretsandredactUrlParamsoptions are conveniences, not security features.
The bigger risk is what the agent reads. A web page is untrusted input. An agent that browses a page with hidden instructions and also has access to your other tools can be steered by that page. Keep browsing agents away from production credentials, use --isolated, and be careful with --extension, which hands the agent your logged-in sessions. More in is MCP safe to use in a company.
What this means for a team
Put Playwright MCP in the shared project config for the developers and testers who use it (see MCP servers in Claude Code for a team), with --isolated as the team default. Agree that it is for exploring and debugging, and that anything that must keep working becomes a real test. And note that what the agent learns about your app while clicking through it, which flows are fragile or which test account to use, disappears at the end of the session unless someone writes it down.
Where Bombos fits
Playwright MCP gives the agent a browser; Bombos gives every AI tool in the team a shared memory, so what one agent learned about your app reaches the next. It is a plugin for Claude Code, Cursor, Codex, Copilot and your other AI tools, with team knowledge, rules the AI learned from corrections, and what already sits in repos, documents and mail, with a trail of what each answer rests on. It runs in our cloud or on your own server, and one developer can try it first with their own agents.
Related questions
How do I add Playwright MCP to Claude Code?
Run claude mcp add playwright npx @playwright/mcp@latest. It needs Node.js 18 or newer. Use --scope project to share it with the team through .mcp.json.
Does Playwright MCP need a vision model?
No. By default it uses the accessibility tree through browser_snapshot. The optional vision capability (--caps=vision) adds coordinate-based mouse tools for elements that are missing from the snapshot.
Can Playwright MCP use my logged-in browser?
Yes, with the --extension option and the Playwright Extension it connects to a running Chrome or Edge and uses your existing tabs and sessions. Think twice before giving an agent that access.
Does Playwright MCP replace writing Playwright tests?
No. The agent explores and checks pages in a session; a written test runs the same way every time in CI. Many teams use the agent to help write tests, then run the tests without the agent.
Why does the browser remember my logins between sessions?
By default Playwright MCP uses a persistent profile in your cache directory. Use --isolated to keep the profile in memory only, or --storage-state to load a specific state.
