Playwright MCP ServerFeatured

What is Playwright MCP Server?

Playwright MCP Server is Microsoft's official playwright mcp package (@playwright/mcp) that gives AI agents browser automation through Playwright. It lets an LLM read and act on web pages through structured accessibility snapshots instead of screenshots, so no vision model is needed.

The project is open source under the Apache-2.0 license and maintained in the microsoft/playwright-mcp repository. It runs locally over stdio by default, and it can also be started as a standalone HTTP server that MCP clients connect to by URL.

How to use Playwright MCP Server?

Prerequisites: Node.js 18 or newer and an MCP client such as Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Codex or Goose. No API key or account is required.

The standard config works in most clients:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

Extra options are added to the args list, for example "--headless", "--browser=firefox" or "--isolated".

Claude Code

claude mcp add playwright npx @playwright/mcp@latest

Claude Desktop

Follow the MCP install guide and paste the standard config above into your Claude Desktop config file.

Cursor

Go to Cursor Settings -> MCP -> Add new MCP Server, choose the command type and enter npx @playwright/mcp@latest. The README also provides a one-click install button.

VS Code

Use the standard config with the VS Code MCP setup, or install from the command line:

code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

The server then becomes available to the GitHub Copilot agent in VS Code.

Codex

codex mcp add playwright npx "@playwright/mcp@latest"

Or add it to ~/.codex/config.toml:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

Windsurf

Follow the Windsurf MCP documentation and use the standard config above.

Standalone HTTP server and Docker

To run the playwright mcp server as a long-lived process (for example on a machine where the IDE cannot open a headed browser), start it with a port:

npx @playwright/mcp@latest --port 8931

Then point the client at the endpoint:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

A Docker image is also published (mcr.microsoft.com/playwright/mcp); it currently supports headless Chromium only.

Key features of Playwright MCP Server

• Accessibility-tree based: agents work from structured page snapshots, not pixels, which makes actions fast and deterministic.
• No vision model needed: any text LLM can drive the browser; screenshots are available but optional.
• Multiple browsers: --browser accepts chrome, firefox, webkit or msedge, and --device or --mobile emulates mobile devices.
• Flexible profiles: a persistent profile by default (logins survive between sessions), --isolated in-memory sessions with optional --storage-state, or the Playwright browser extension to reuse tabs in your running Chrome or Edge.
• Opt-in capabilities: extra tool groups such as PDF export, coordinate-based mouse control, DevTools tracing and video, storage, network routing and test assertions are enabled with --caps.
• Fine-grained configuration: every CLI flag has a PLAYWRIGHT_MCP_* environment variable, and a JSON file can be loaded with --config.
• Network controls: proxy settings, --allowed-origins and --blocked-origins lists, and --allowed-hosts for the HTTP server.

Playwright MCP Server tools

The default toolset covers core automation:

• Navigation and pages: browser_navigate, browser_navigate_back, browser_resize, browser_close and browser_tabs for listing, opening, closing and switching tabs.
• Reading the page: browser_snapshot captures the accessibility snapshot that agents use to target elements; browser_find searches that snapshot for text or a regex, which is cheaper than a full snapshot. browser_take_screenshot saves an image but cannot be used to pick targets.
• Interaction: browser_click, browser_type, browser_fill_form, browser_select_option, browser_hover, browser_drag, browser_press_key, browser_file_upload, browser_drop and browser_handle_dialog.
• Debugging: browser_console_messages, browser_network_requests and browser_network_request for headers and bodies, plus browser_evaluate for JavaScript and browser_wait_for for text or timeouts.
• Code execution: browser_run_code_unsafe runs a Playwright snippet in the server process; the README labels it RCE-equivalent.

Opt-in groups add tools such as browser_pdf_save (--caps=pdf), browser_mouse_click_xy (--caps=vision), browser_start_tracing (--caps=devtools), browser_cookie_list (--caps=storage), browser_route (--caps=network) and browser_verify_text_visible (--caps=testing).

Use cases of Playwright MCP Server

• Exploratory testing: "Open localhost:3000, sign up with a test account and tell me which step fails."
• Writing end-to-end tests: let the agent walk through a flow, then generate Playwright code (the --codegen option sets TypeScript, Python, Java or C#).
• Self-healing tests: have the agent inspect the current page structure and fix broken selectors in a failing test.
• Debugging front-end issues: "Load the checkout page and list any console errors and failed network requests."
• Form filling and data entry in web apps that have no API, using a persistent or extension-connected logged-in session.
• Long-running agent workflows that need to keep browser state across many steps.

Playwright MCP Server vs alternatives

• Playwright CLI + Skills: Microsoft's README recommends Playwright CLI for coding agents because CLI calls are more token-efficient. The MCP server fits agent loops that benefit from persistent state and rich page introspection.
• Puppeteer MCP Server: a Puppeteer-based browser server; Playwright MCP adds multi-browser support and accessibility-snapshot targeting.
• Browser Tools MCP: focused on reading logs and audits from your own Chrome via an extension, rather than driving the browser end to end.

Troubleshooting Playwright MCP Server

• Headed browser will not open from the IDE: on systems without a display, or when the IDE runs the server in a worker process, start the server yourself in an environment with a display using --port 8931 and connect by url.
• Conflicts when several clients run at once: a persistent profile can be used by only one browser at a time. Start additional clients with --isolated or a distinct --user-data-dir.
• A tool you expect is missing: PDF, vision, DevTools, storage, network and testing tools are off by default; enable them with --caps, for example --caps=pdf.
• Cannot read local files or file:// URLs: file access is restricted to workspace roots by default. --allow-unrestricted-file-access lifts this, so use it with care.
• Docker run fails with a headed browser: the Docker image only supports headless Chromium.