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.
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
--headlessif 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.
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):
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}Claude Code
From a terminal:
claude mcp add playwright npx @playwright/mcp@latestRestart 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:
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:
codex mcp add playwright npx "@playwright/mcp@latest"[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:
{
"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(orchrome,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-stateand 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:
{
"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:
{
"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:
npx @playwright/mcp@latest --port 8931{
"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
- Confirm the Playwright server is listed and running in your client.
- Ask: "Navigate to https://demo.playwright.dev/todomvc and add a few todo items."
- 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 --versionin a terminal (you want 20 or newer), then runnpx @playwright/mcp@latestthere 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
--isolatedor a separate--user-data-dirfor 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.
- Playwright docs: Playwright MCP (setup, flags, standalone server)
- microsoft/playwright-mcp README (client configs, flags, Docker, security)
- Claude Code docs: Connect Claude Code to tools via MCP
- OpenAI Codex docs: Model Context Protocol
PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email pluginstackai@gmail.com.
Related guides
Tools in this guide
Get new guides by email
New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.