Catalog My learning Blog
MCP Setup Guides: Cursor, Codex, Gemini CLI and Top Servers · Phase 2 · Lesson 7 · 4 min read

Playwright MCP Server Setup Guide

On this page
  1. Why give an agent a browser
  2. How it sees the page
  3. Add it to your tool
  4. The tools you'll see most
  5. Flags worth knowing
  6. Check it works
  7. Check yourself

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:

Code
claude mcp add playwright -- npx -y @playwright/mcp@0.0.84

Cursor, Claude Desktop, JetBrains and other clients that use mcpServers:

JSON
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@0.0.84"]
    }
  }
}

VS Code (.vscode/mcp.json):

JSON
{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@0.0.84"]
    }
  }
}

Codex CLI and Gemini CLI:

Code
codex mcp add playwright -- npx -y @playwright/mcp@0.0.84
gemini mcp add -s user playwright npx -y @playwright/mcp@0.0.84

This 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

ToolWhat it does
browser_navigateOpens a URL
browser_snapshotReturns the accessibility snapshot the agent uses to find elements
browser_click, browser_type, browser_fill_formClicks and types into elements from the snapshot
browser_take_screenshotSaves an image, for you or for a model that can read images
browser_console_messages, browser_network_requestsReads the console and network log, useful for debugging
browser_evaluateRuns 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:

  • --headless runs without a visible window. The default is headed, so you can watch what the agent does.
  • --browser picks the browser: chrome, firefox, webkit or msedge.
  • --isolated keeps 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 --isolated or its own --user-data-dir.
  • --storage-state=path/to/state.json loads saved cookies, so the agent starts logged in to your test account.
  • --allowed-origins limits which sites the browser may request, as a semicolon-separated list.

For example, a headless, isolated browser for CI-like checks:

Code
"args": ["-y", "@playwright/mcp@0.0.84", "--headless", "--isolated"]
WarningPlaywright MCP is not a security boundary, and the project says so. --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.