Playwright MCP: a Playwright MCP server for AI agents
Playwright MCP turns Claude, Cursor, VS Code, and other MCP clients into a browser they can click, type into, and read without taking a screenshot. It earns its place once an AI assistant needs to test a UI or check what a page renders, because the accessibility tree hands the model structured elements instead of pixels to guess at. One catch: Microsoft's own docs steer coding agents toward the separate CLI+SKILLS package instead.
What is Playwright MCP?
Playwright MCP is a Model Context Protocol server built on Microsoft's Playwright framework that gives any MCP-compatible AI client a working browser. Instead of screenshots and vision models, it exposes each page as an accessibility tree — a structured snapshot of buttons, links, and form fields the LLM can act on directly. The README frames this as more deterministic than pixel-based automation, since there's no coordinate guessing involved.
Key features
- ✓Uses Playwright's accessibility tree instead of screenshots, so no vision model is needed to find a button or a link.
- ✓Deterministic tool calls — the README says this avoids the ambiguity that comes with screenshot-based clicking.
- ✓`--browser` selects chrome, firefox, webkit, or msedge, and the server runs headed by default unless you pass `--headless`.
- ✓Persistent profile by default, so logins survive between sessions until you delete the profile folder yourself.
- ✓`--isolated` mode for throwaway sessions that discard all storage state the moment the browser closes.
- ✓Optional capability flags (`--caps vision,pdf,devtools`) extend the tool set past the accessibility-only defaults.
- ✓A Chrome/Edge browser extension lets the server attach to tabs you already have open, logins and all.
Installing Playwright MCP
Playwright MCP needs Node.js 18 or newer and an MCP client — VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Goose, Grok, Junie, or any other MCP-compatible tool. The standard install adds this block to your client's MCP config: ```js { "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } } ``` Claude Code users can skip the JSON and run `claude mcp add playwright npx @playwright/mcp@latest` directly. VS Code, Codex, Copilot, Factory, and Grok each have their own one-line CLI equivalents documented in the README. Past that first block, the server accepts a long list of flags — `--browser`, `--headless`, `--isolated`, `--caps`, `--viewport-size`, `--proxy-server`, and dozens more — each settable as a CLI arg or an environment variable, which is how you pin a browser channel, restrict file access, or route traffic through a proxy.
Using Playwright MCP with your AI assistant
Once the server is registered, the AI assistant sees a set of browser tools — navigate, click, type, snapshot — and decides when to call them based on the conversation. Behavior differs by mode. The default persistent profile keeps you logged into whatever sites you've already authenticated, which is handy for poking around real accounts, but two clients pointed at the same workspace will fight over the same profile lock. Switch to `--isolated` and each session starts clean, optionally seeded from a `--storage-state` file. If you'd rather reuse a browser window you already have open, with its existing tabs and cookies intact, the Playwright MCP Chrome Extension connects to it instead of launching a new instance. For setup beyond login state, `--init-script` runs a JS file before every page's own scripts, and `--init-page` runs a TypeScript file against the Playwright `page` object once per session.
Strengths
- ✓Structured accessibility snapshots give the model exact element references instead of asking it to guess coordinates from a screenshot.
- ✓One `npx` command and a four-line JSON block covers install for most clients.
- ✓Config flags cover real operational needs: proxy routing, HTTPS-error bypass, permission grants, custom viewport, and CDP connection to an already-running browser.
- ✓Session model is flexible — persistent, isolated, or attach-to-existing-tabs via the extension — instead of one-size-fits-all.
Known limitations
- △The README itself steers coding agents toward the separate Playwright CLI+SKILLS package instead, citing token cost from large tool schemas and verbose accessibility trees.
- △A persistent profile is single-instance: two MCP clients sharing a workspace will conflict unless you pass `--isolated` or a distinct `--user-data-dir` to each.
- △`--allowed-origins` and `--blocked-origins` are documented as not a security boundary and not effective against redirects, so don't rely on them to sandbox untrusted sites.
- △Configuration lives entirely in CLI flags and environment variables. There's no GUI. Getting browser choice, viewport, and permission grants right means reading the flag table.
Alternatives to Playwright MCP
Who should use Playwright MCP
Playwright MCP fits developers wiring an AI assistant into browser-based work: QA engineers who want an agent to poke at a staging site, teams doing exploratory testing where a fixed script doesn't fit, and anyone building an agentic workflow around Claude, Cursor, or another MCP client that needs to read and act on a real page. It's a weaker fit for a coding agent that's mostly editing files and running a test suite — the README's own comparison section says the separate CLI+SKILLS package suits that high-throughput, context-constrained case better.
Frequently asked questions
Playwright MCP is the MCP interface into Playwright, built for agentic loops that need persistent browser state and iterative reasoning over page structure. The README recommends the separate Playwright CLI+SKILLS package for coding agents instead, since CLI invocations skip loading large tool schemas and verbose accessibility trees, which saves context when an agent is also juggling a codebase.
Playwright MCP documents setup for VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Cline, Codex, Copilot, Factory, Gemini CLI, Goose, Grok, Junie, Kiro, LM Studio, opencode, Qodo Gen, Warp, Amp, and Antigravity, plus any other MCP-compatible client using the same standard JSON config.
Multiple MCP clients can use Playwright MCP at once, but the default persistent profile only allows one browser instance at a time, so two clients sharing a workspace will conflict. Start each additional client with the `--isolated` flag or a separate `--user-data-dir`, or use `--shared-browser-context` to have several HTTP clients deliberately reuse one browser context.
Playwright MCP stores login state in a persistent browser profile by default, so a session authenticated once stays logged in across later calls until the profile is deleted. Switching to `--isolated` mode discards all storage state when the browser closes instead, though you can seed it upfront via a `--storage-state` file or the config's `contextOptions`.
Playwright MCP supports chrome, firefox, webkit, and msedge, selected with the `--browser` flag or the `PLAYWRIGHT_MCP_BROWSER` environment variable. It also has a `--device` option for emulating a specific device profile and a `--mobile` flag for generic mobile emulation.
Playwright MCP is free and open source, released by Microsoft under the Apache-2.0 license. There's no paid tier described in the repository — you install it with `npx` and run it locally against your own browser.
The problem it solves
AI coding assistants can read and write code but have no built-in way to see a rendered web page. A screenshot burns vision-model tokens and still leaves the model guessing at pixel coordinates for a button that might be a few pixels off. Playwright MCP solves the narrower problem of giving an MCP client the same structured view of a page that a screen reader gets: an accessibility tree of labeled, actionable elements, so the model can act on "the Submit button" instead of coordinates.
Best use cases
- •Exploratory QA: point an agent at a staging build and have it click through flows the way a human tester would.
- •Self-healing test maintenance, where an agent checks a broken selector against the live accessibility tree and proposes a fix.
- •Form-filling and data-entry automation driven by natural-language instructions instead of hand-written Playwright scripts.
- •Long-running autonomous workflows that need browser context to persist across many tool calls, per the README's own MCP-vs-CLI guidance.
Related repositories
Is playwright-mcp worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of playwright-mcp.