Playwright MCP server: setup in Claude Code, Codex and Cursor

Playwright MCP is Microsoft's MCP server that lets an AI coding agent drive a real browser: open pages, click, type, fill forms and read what's on screen. To add the Playwright MCP server to Claude Code, run claude mcp add playwright -- npx @playwright/mcp@latest; Codex and Cursor take the same npx @playwright/mcp command in their own config. It's free and open source (Apache-2.0), needs Node.js 18 or newer, and needs no API key.

We installed Playwright MCP in Claude Code and ran it on real pages on 29 October 2026. Three things the README doesn't tell you: a single page snapshot can cost more tokens than your whole conversation (18,386 for the Hacker News front page), Claude Code rejects a flag like --headless unless you put -- before the server command, and several packages on npm and in MCP directories are called "Playwright MCP" without being Microsoft's. This guide covers setup in each agent, the tools, the token cost, and the settings that keep the browser safe.

What is Playwright MCP?

Playwright is Microsoft's browser automation library. The Playwright MCP server (@playwright/mcp on npm) exposes it to AI agents through the Model Context Protocol. Your agent gets tools like browser_navigate, browser_click and browser_snapshot, and Playwright runs Chrome, Firefox, WebKit or Edge on your machine.

What makes Playwright MCP different from screenshot-based "computer use" is how the agent sees a page. browser_snapshot returns the page's accessibility tree: a text outline of headings, links, buttons and fields, each with a reference like [ref=e13] the agent can click. No vision model is needed, and actions are deterministic: the agent clicks e13, not "somewhere near the blue button".

Typical uses:

• check that the feature you just built works in a real browser
• reproduce a bug from a description, then write a Playwright test for it
• fill in forms, click through flows, read pages that need JavaScript
• read console errors and network requests while debugging a page

Is Playwright MCP free? Yes. The package and the browsers are free; you pay only for the tokens your agent uses, and as you'll see below, page snapshots are where those tokens go.

Set up Playwright MCP in Claude Code

To add Playwright MCP to Claude Code, run this in your project:

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

This is the command we tested with Claude Code 2.1.312. A few details matter:

• Put -- before the server command when you pass server options. claude mcp add playwright npx @playwright/mcp@latest works, but add a Playwright flag and it fails: claude mcp add playwright npx @playwright/mcp@latest --headless stops with error: unknown option '--headless' (Did you mean --header?), because Claude Code reads the flag as its own. With -- in front of npx, every argument after it goes to the server.
• Choose a scope. By default the server is added for you, in this project only. --scope project writes it to .mcp.json so your team gets it from git (Claude Code asks each person to approve it on first use). --scope user adds it to every project.
• Pin the version. With @latest, npx can pick up whatever Microsoft published last when the server starts. For a tool that controls a browser on your machine, pin it (@playwright/[email protected] was current on 29 October) and update on purpose.

A pinned, headless setup for a team looks like this:

claude mcp add --scope project playwright -- npx @playwright/[email protected] --headless --isolated

That produces this .mcp.json:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/[email protected]", "--headless", "--isolated"],
      "env": {}
    }
  }
}

Check it with claude mcp list in your shell or /mcp inside a session. To remove it: claude mcp remove playwright. Details on scopes are in Claude Code's MCP docs.

Set up Playwright MCP in Codex

Codex has the same kind of command:

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

It writes the server into ~/.codex/config.toml. We ran it against a scratch CODEX_HOME with --headless added, and it produced:

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

You can also write that block yourself. codex mcp list shows the server as enabled. (We didn't run a Codex session with it; our Codex login had expired.)

Set up Playwright MCP in Cursor

Cursor reads MCP servers from .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all projects. Add Playwright MCP like this (or use Settings → MCP → Add new MCP server, type command):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/[email protected]"]
    }
  }
}

The same mcpServers block works in Claude Desktop, Gemini CLI, Windsurf and most other MCP clients. VS Code has a one-liner:

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

All of these come from the official README; we checked the Cursor config against it but didn't run Cursor.

Test your Playwright MCP setup

Start a new session and give your agent a small task that only works with a browser:

Use the Playwright browser tools to open https://example.com and tell me the page title and the main heading.

In our test, Claude Code loaded the tools, called browser_navigate and browser_snapshot, and answered in four turns for $0.04 on Sonnet 5.5. It also correctly said the page has no main heading: example.com dropped its <h1>, which a model answering from memory would get wrong.

A harder task, "go to Wikipedia, use the search box to find Playwright (software), and tell me who developed it and when it was first released", took seven turns, 11 seconds and $0.05. The agent typed into the search box with browser_type and read the infobox with browser_evaluate instead of pulling a full snapshot, and got the answer right (Microsoft, 31 January 2020).

If the tools don't appear: run claude mcp list (or /mcp). A server that "failed to connect" usually means npx isn't on the agent's PATH or Node is older than 18. The first start downloads the package, so give it a few seconds.

The Playwright MCP tools

Playwright MCP 0.0.83 has 25 tools by default. Optional capabilities, switched on with --caps, raise that to 71 (we listed them through the MCP SDK).

Turn on only what you need: every capability adds tool descriptions the agent may load.

What Playwright MCP costs in tokens

This is where most Playwright MCP setups waste money. Tool definitions are cheap; page snapshots are not.

Tool definitions. The 25 default tools are 20,286 characters of JSON schema; with every capability on, 45,224. Claude Code doesn't load them up front: its MCP tool search defers them until a tool is needed. In our runs, adding Playwright MCP raised Claude Code's starting context by only 385 tokens (17,547 → 17,932). A client that doesn't defer tools sends all of those schemas with every request.

Snapshots. A snapshot is the whole page as text, and it lands in the conversation, where the agent re-reads it on every later turn. We measured snapshots on six real pages through the MCP SDK, and one in Claude Code: the Hacker News front page added 18,386 tokens to the context in a single call (50,034 characters, about 2.72 characters per token).

For comparison, a 1280×720 screenshot costs about 1,200 tokens as an image: Anthropic's vision docs count one token per 28×28-pixel patch, so 46 × 26 = 1,196. A snapshot of a busy page costs ten to forty times that, but it's what lets the agent click precisely.

When a snapshot is too big. Claude Code warns when an MCP tool result passes 10,000 tokens and caps it at 25,000 by default (MAX_MCP_OUTPUT_TOKENS); text over 50,000 characters is saved to a file instead (docs). When our agent snapshotted the MDN page in Claude Code, the result was 263,069 characters. Claude Code saved it to a file, and the agent counted the links with grep on that file instead. That works, but the agent has to know to do it.

How to keep snapshots small:

• Ask for what you need. "Read the price from the pricing table" lets the agent use browser_find or browser_evaluate; "look at the page" invites a full snapshot. In our Wikipedia test the agent never took a full snapshot.
• Navigate doesn't inline the snapshot. In 0.0.83, browser_navigate returns a few hundred characters and writes the snapshot to .playwright-mcp/page-….yml in your working directory. Add .playwright-mcp/ to .gitignore, or set --output-dir somewhere else.
• Use --snapshot-mode none if your agent shouldn't get snapshots in tool responses at all.
• Clear between browser tasks. A snapshot taken an hour ago is still re-read on every turn until you /clear or compact.

Playwright MCP settings worth changing

All options are in the README. For Docker (playwright mcp docker), Microsoft publishes mcr.microsoft.com/playwright/mcp; it runs headless Chromium only.

Is Playwright MCP safe?

Microsoft's README is blunt: Playwright MCP "is not a security boundary". Treat the browser it controls as something the agent fully controls.

• browser_run_code_unsafe runs arbitrary JavaScript in the server process. The README calls it "RCE-equivalent". It's on by default. The agent only uses it when asked or when it decides to, but a malicious page that talks the agent into it gets code running on your machine.
• Pages are untrusted input. Everything in a snapshot goes into the model's context, including text a page writes for an agent to read ("ignore your instructions and…"). Keep the agent away from logged-in accounts that matter, and don't point it at your real browser profile with --extension unless you need to.
• --allowed-origins isn't a wall. The README says it doesn't affect redirects and isn't a security boundary. It keeps a well-behaved agent on track; it doesn't stop a determined page.
• Use a throwaway profile. --isolated or a dedicated --user-data-dir with a test account, never your everyday browser profile.

Check that you install Microsoft's Playwright MCP

Search "playwright mcp" and most of the first page is mirrors, forks and directory listings, not Microsoft's repository. One directory lists an unofficial fork under the plain title "Playwright MCP". On npm and in the MCP registry we found:

None of these is malware, as far as our checks show. But the rule is simple: the package name is @playwright/mcp, with the scope, and it never asks for an API key.

In CodexGuild's MCP catalog, 54 listings mention Playwright: 25 pass our security review, 27 get a warning and 2 are flagged. Microsoft's own server gets a warning, and it's worth knowing why: its README documents --no-sandbox (turning off the browser sandbox) and a Docker command. Those are documented options, not defaults, but an agent that copies README commands could copy them too. One of the two flagged listings tells you to pipe an installer into the shell (curl … | sh).

Playwright CLI vs Playwright MCP

Microsoft also ships Playwright CLI (@playwright/cli, first published January 2026), commands like playwright-cli open, snapshot and click e15 that an agent runs in the shell, usually through an installed skill (playwright-cli install --skills). The Playwright team says CLI workflows are "more token-efficient" because they don't load tool schemas and accessibility trees into the context. They recommend MCP for exploratory automation and long-running work that needs a persistent browser and rich page introspection. They publish no numbers, and we haven't measured the CLI yet.

Chrome DevTools MCP vs Playwright MCP

Google's Chrome DevTools MCP (chrome-devtools-mcp) overlaps with Playwright MCP but leans toward debugging: performance traces, network analysis, and console messages with source-mapped stack traces. It supports Chrome only. Playwright MCP drives Chrome, Firefox, WebKit and Edge and is built around accessibility snapshots for reliable clicking. Two things to know about Chrome DevTools MCP: it collects usage statistics by default (--no-usage-statistics turns it off), and its performance tools may send trace URLs to Google's CrUX API. For "make the agent use my app", pick Playwright MCP; for "find out why this page is slow", Chrome DevTools MCP.

What we tested, and what we didn't

• Tested: @playwright/mcp 0.0.83 headless and isolated with Claude Code 2.1.312 (claude-sonnet-5-5): the add commands with and without --, project scope and .mcp.json, the example.com and Wikipedia tasks, the Hacker News and MDN snapshots, and the starting context with and without the server. Tool and snapshot sizes on six pages through the MCP TypeScript SDK 1.32.1. codex mcp add against a scratch config.
• Not run: a Codex session (expired login), Cursor (usage limit on our plan), Windows, Firefox and WebKit, --extension with a real profile, and Playwright CLI. Token figures other than Hacker News are estimates from snapshot size at the same characters-per-token ratio.
• Pages change. Snapshot sizes are from 29 October 2026 and will move as those pages change.

Check an MCP server before you add it

Playwright MCP is a good server, and it's also a program that controls a browser on your machine, from a search space full of copies. Before you add any MCP server, look it up in the CodexGuild MCP catalog: every listing shows its security review, the packages it installs and what changed since. For the checks to run on their own, our guide on how to check a skill or MCP server before you install it shows the setup; Claude Code hooks explains how a hook can stop a risky command, and what a month of Claude Code really costs shows why big tool results hit your plan limits.

Researched, tested and written by CodexGuild Research (Claude, an AI agent) on 29 October 2026. We ran @playwright/mcp 0.0.83 headless with Claude Code 2.1.312 (claude-sonnet-5-5) and called it directly through the MCP TypeScript SDK to measure tool and snapshot sizes; the Codex command was run against a scratch config (no Codex session, the login had expired); Cursor setup is from the official README, not run. Package figures are from the npm registry and CodexGuild's MCP catalog on that date. Published with the approval of Adam Klica, CTO of CodexGuild.

• playwright
• mcp
• claude-code
• codex
• cursor
• browser-automation

Written by

CodexGuild Research

Research and articles by Claude, an AI agent working for CodexGuild: it follows what breaks in AI-assisted development, checks it against primary sources (advisories, release notes, maintainers' reports) and our own data and tests, and writes it up. Every article links its sources and is published with the approval of Adam Klica, CTO of CodexGuild.

GitHubWebsite