Installing Playwright MCP

Playwright MCP exposes browser automation as MCP tools. Setup needs no prior installation: the server is launched via npx, which downloads it on the fly.

Requirement for Playwright MCP

Node.js 18 or newer. Check your version with:

node --version

Registering Playwright MCP with your client

MCP clients read their servers from a JSON configuration. The entry for Playwright MCP looks like this:

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

Where this file lives differs by client. The official repository documents setup for, among others, Codex, Claude Code, Cursor, VS Code, Copilot, Cline, Gemini CLI, LM Studio, Warp and Windsurf.

Running Playwright MCP without a client

To try it out, you can also run the server directly:

npx @playwright/mcp@latest

On first run, npx downloads the @playwright/mcp package. After that, the server is ready and the client can use its tools.

Playwright MCP in Docker

For container use, the documentation notes that only headless Chromium is currently supported.

Common sources of error

If the client offers no Playwright tools after configuration, it's usually a malformed JSON structure in the MCP configuration file — a missing comma or bracket is enough for the entire entry to be ignored. A second common pitfall is an outdated Node.js version; node --version should show at least 18, otherwise the npx call fails or the server starts with errors. In headless environments without a graphical interface (such as a server), the default mode with a visible browser doesn't work — starting with an additional headless flag solves that.

Verifying the setup

After restarting the client, check whether the connection works with a simple task, such as "Open the homepage of example.com and describe what you see." If the agent responds with a description of the actual page instead of an error message, the server is set up correctly. For debugging purposes, a trace can additionally be recorded that shows in detail which actions the agent performed in the browser.

For production automation

Anyone using Playwright MCP long-term for tests or recurring automation should consider an isolated browser profile so that login credentials and session state aren't accidentally shared between tasks. For CI/CD pipelines, headless mode combined with Docker is the best fit, since no graphical interface is available there anyway.

Running multiple browser instances in parallel

Anyone running several independent automation tasks at once should start a separate server instance with its own port for each task, rather than sharing one instance. This prevents parallel tasks from closing each other's tabs or overwriting state.

This becomes especially important in CI pipelines running multiple jobs concurrently, where a shared instance can otherwise cause hard-to-diagnose flaky test failures.

Source: github.com/microsoft/playwright-mcp, checked on 2026-09-02.