Ad space · Your tool here
PluginStack
Setup guide

How to set up the Playwright MCP server in Claude Code, Cursor, VS Code and Codex

Checked against the official docs:

Microsoft's Playwright MCP server gives an AI assistant a real browser. It works from the page's accessibility tree rather than screenshots, so no vision model is required. You add one npx command to your MCP config and the assistant can open pages, click, type and check the result. This guide covers Claude Code, Cursor, VS Code and Codex, useful flags, Docker, and what to do when the server will not start. It's based on the official Playwright MCP documentation and repository (checked 20 November 2026).

Get new guides by email

New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.

The newsletter hasn't started sending yet. Join the list now and we'll email you when the first issue goes out. From PluginStack (pluginstackai@gmail.com). Privacy policy.

Quick answer

  • Needs: Node.js 20 or newer, and an MCP client such as VS Code, Cursor, Claude Code, Claude Desktop or Codex.
  • Standard config: run npx @playwright/mcp@latest. This works in most clients.
  • Claude Code: claude mcp add playwright npx @playwright/mcp@latest
  • Codex: codex mcp add playwright npx "@playwright/mcp@latest"
  • VS Code: code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}' or use the one-click install on the Playwright MCP docs.
  • The browser is headed by default, so you can watch what it does. Pass --headless if you want it hidden.

Free: MCP Starter Checklist

One page: Inspector smoke-test, Claude Code + Cursor connect steps, and the stdout gotcha. Join the list and download it free.

Markdown download + occasional PluginStack updates. No spam. Privacy policy.

Before you start

  • Check Node.js: run node --version. The official docs require Node.js 20 or newer (older PluginStack pages said 18; the current requirement is 20).
  • The assistant can use a real browser on your machine. It can open pages, fill forms and, depending on the flags, reach files or other origins. Keep tool approval on until you trust the setup, and don't point it at accounts or data you wouldn't hand to the assistant.
  • Playwright MCP is not a security boundary. Microsoft says this plainly, and points to the MCP security best practices. Flags that limit origins or file access help, but they are not a complete sandbox.

If you are using a coding agent and mainly want concise browser commands, Microsoft also publishes Playwright CLI with skills, which it says can be more token-efficient than the MCP server. This guide covers the MCP server. For a shorter overview, see the Playwright MCP listing.

What it does

When a tool runs, the server returns a structured snapshot of the page: headings, buttons, text boxes and a short reference for each element. The model uses those references to click or type, then reads a fresh snapshot to see what changed. You can also ask it to take a screenshot, inspect network traffic or save and restore login state.

A first prompt from the official docs: "Navigate to https://demo.playwright.dev/todomvc and add a few todo items."

Standard config

This mcpServers block is the official standard config and works in most clients. Put it in your client's MCP file (~/.cursor/mcp.json or a project .cursor/mcp.json in Cursor; claude_desktop_config.json in Claude Desktop; the equivalent file in other apps):

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

Claude Code

From a terminal:

bash
claude mcp add playwright npx @playwright/mcp@latest

Restart Claude Code, then run claude mcp list and try the demo prompt above. More Claude Code MCP commands: best MCP servers for Claude Code.

Cursor

Open Cursor Settings → MCP → Add new MCP Server, choose the command type, and use npx @playwright/mcp@latest. Or paste the standard config into ~/.cursor/mcp.json and restart Cursor. Details on those files: how to add an MCP server to Cursor.

VS Code

Install with the VS Code CLI, which adds the server to your user profile, or follow the MCP install UI and use the standard config. After it is added, it is available to the GitHub Copilot agent:

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

If you are writing .vscode/mcp.json yourself, that file uses a top-level servers key and a type of stdio. See how to add an MCP server to VS Code.

Codex

From a terminal, or by editing ~/.codex/config.toml:

bash
codex mcp add playwright npx "@playwright/mcp@latest"
~/.codex/config.toml
text
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

More on Codex MCP files: how to add an MCP server to Codex.

Cline and other clients

The same standard config works with most MCP clients, including Windsurf, Cline, Goose and Copilot CLI. Cline's official example lives in cline_mcp_settings.json and adds "type": "stdio", a timeout of 30, and -y before the package name so npx does not prompt:

cline_mcp_settings.json
json
{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ],
      "disabled": false
    }
  }
}

Useful flags

Pass flags in the args list after @playwright/mcp@latest. The ones people use most:

  • --headless — hide the browser window. Headed is the default.
  • --browser=firefox (or chrome, webkit, msedge) — pick a browser. The default is Chrome.
  • --isolated — keep the profile in memory and start fresh each session. You can load cookies with --storage-state and a storage-state file.
  • --extension — connect to a running Chrome or Edge browser with the Playwright extension, so the assistant can use tabs you already have open. See the Playwright extension readme for install steps.
  • --config — point at a JSON config file for more options (timeouts, network rules and so on). The schema is in the Playwright MCP repository.

By default the server uses a persistent profile, so logins and cookies are kept between sessions. The profile lives in a ms-playwright folder in your platform's cache directory, with a name that includes the browser and a hash of the project, so different projects stay separate. Override the location with --user-data-dir. Only one browser instance can use a given persistent profile at a time; if two clients share a workspace, start the extra one with --isolated or a different user-data directory.

A headless browser the server launched is closed after an hour with no completed tool calls (the next tool call starts a new one). Headed browsers, and browsers attached with --extension or a CDP endpoint, are not closed automatically. Pass --idle-timeout with a time in milliseconds to change this, or 0 to turn it off.

Example: headed is default, so this runs the browser hidden in Firefox:

json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--browser=firefox"
      ]
    }
  }
}

Docker and a standalone server

You can run the official image mcr.microsoft.com/playwright/mcp instead of npx. Microsoft notes that the Docker image currently only supports headless Chromium:

json
{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

If you need a headed browser on a machine with no display, or the client starts the server from a worker process, run a standalone HTTP server yourself in an environment that has a display, then point the client at it:

bash
npx @playwright/mcp@latest --port 8931
json
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

HTTP sessions use a five-second heartbeat. If your client or proxy does not answer those pings, set the PLAYWRIGHT_MCP_PING_TIMEOUT_MS environment variable to a longer timeout in milliseconds, or 0 to disable the heartbeat.

Check that it works

  1. Confirm the Playwright server is listed and running in your client.
  2. Ask: "Navigate to https://demo.playwright.dev/todomvc and add a few todo items."
  3. You should see a browser window (unless you passed --headless), and the assistant should report what it added.

Troubleshooting

  • The server will not start, or you see `spawn npx ENOENT`: Node.js may be missing, too old, or not on the PATH your client sees. Run node --version in a terminal (you want 20 or newer), then run npx @playwright/mcp@latest there and read the error. On Windows, see Fix "spawn npx ENOENT".
  • It starts and then exits: that is often MCP error -32000 "Connection closed". Check the client's MCP logs.
  • Headed browser fails on a server or in an IDE worker: start the standalone HTTP server from an environment that has a display, as in the Docker and standalone section, and point the client at that URL.
  • Two clients fight over the same profile: use --isolated or a separate --user-data-dir for the second client.
  • The agent never opens the browser: check the server is enabled and its tools are allowed for the session, then name Playwright in the prompt.

FAQ

Do I need a paid Playwright or browser license?

No. You need Node.js 20 or newer and a supported MCP client. The server launches a browser on your machine with the official Playwright MCP package.

Do I need a vision model?

No. The default path uses the page's accessibility tree, not screenshots. You can still ask for a screenshot when you want to see the page.

Should I use this or Chrome DevTools MCP?

They solve different jobs. Playwright MCP is for driving and testing a browser (click, type, check a flow). Chrome DevTools MCP is for inspecting and debugging a page. You can install both.

Can Cline use it?

Yes. Playwright's README includes a Cline example, which is in the Cline section above. See the Cline listing if you are setting Cline up as well.

Sources

Commands and config above come from these official docs. Tools change often, so check them for the latest steps.

PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email pluginstackai@gmail.com.

Get new guides by email

New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.

The newsletter hasn't started sending yet. Join the list now and we'll email you when the first issue goes out. From PluginStack (pluginstackai@gmail.com). Privacy policy.