Playwright MCP Server Setup Guide
On this page
Why give an agent a browser
Your agent just changed a signup form. Did it work? Without a browser it can only guess from the code. With Playwright MCP connected, you can say "open localhost:3000/signup, fill in the form with a test user and tell me what happens", and the agent does it.
Playwright MCP is Microsoft's server, and it's one of the most installed MCP servers there is. It runs locally and starts a browser for you.
How it sees the page
Most browser automation for AI started with screenshots: the model looks at an image and guesses where to click. Playwright MCP works differently by default. It reads the page's accessibility tree, the same structured list of buttons, links and fields that screen readers use, and gives the agent a text snapshot with a reference for each element. The agent then says "click the element called Sign up", not "click at x=412, y=300".
That's faster, uses fewer tokens than images, and doesn't break when the layout shifts. If you need pixel-based interaction for a canvas or a chart, you can turn on vision tools with --caps=vision.
Add it to your tool
The server runs with npx, so you need Node.js 18 or newer. The version below was current in November 2026; pin the one you've tried.
Claude Code:
claude mcp add playwright -- npx -y @playwright/mcp@0.0.84Cursor, Claude Desktop, JetBrains and other clients that use mcpServers:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@0.0.84"]
}
}
}VS Code (.vscode/mcp.json):
{
"servers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@0.0.84"]
}
}
}Codex CLI and Gemini CLI:
codex mcp add playwright -- npx -y @playwright/mcp@0.0.84
gemini mcp add -s user playwright npx -y @playwright/mcp@0.0.84This exact version was tested in November 2026: it connected through Gemini CLI 0.67, and the MCP Inspector listed 25 tools.
The tools you'll see most
| Tool | What it does |
|---|---|
browser_navigate | Opens a URL |
browser_snapshot | Returns the accessibility snapshot the agent uses to find elements |
browser_click, browser_type, browser_fill_form | Clicks and types into elements from the snapshot |
browser_take_screenshot | Saves an image, for you or for a model that can read images |
browser_console_messages, browser_network_requests | Reads the console and network log, useful for debugging |
browser_evaluate | Runs JavaScript in the page |
There's also browser_run_code_unsafe, which runs arbitrary Playwright code. The project describes it as equivalent to remote code execution. Treat any request to use it with care.
Flags worth knowing
Add flags after the package name in args:
--headlessruns without a visible window. The default is headed, so you can watch what the agent does.--browserpicks the browser:chrome,firefox,webkitormsedge.--isolatedkeeps the browser profile in memory, so nothing is saved between sessions. Without it, Playwright MCP uses a persistent profile, and that profile can only be used by one browser at a time. If you run two agents at once, give each one--isolatedor its own--user-data-dir.--storage-state=path/to/state.jsonloads saved cookies, so the agent starts logged in to your test account.--allowed-originslimits which sites the browser may request, as a semicolon-separated list.
For example, a headless, isolated browser for CI-like checks:
"args": ["-y", "@playwright/mcp@0.0.84", "--headless", "--isolated"]--allowed-origins helps keep the agent on track, but it doesn't stop redirects. Don't point the agent at untrusted sites while it's logged in to accounts that matter, because page content can carry prompt injection.Check it works
Ask: "Open https://example.com and tell me the main heading." The agent should call browser_navigate, then browser_snapshot, and answer "Example Domain". If a browser window opens and closes right away, run the npx command in a terminal to see the error. A missing browser or an old Node version are the usual causes.
Check yourself
Probably not. The default snapshot mode finds elements by role and name in the accessibility tree, which is more stable than coordinates. Check that the button has a clear accessible name.
Both are trying to use the same persistent profile, which only one browser can use at a time. Use --isolated or a different --user-data-dir for each.
Save a logged-in session to a storage state file and start the server with --storage-state=path/to/state.json.