# Playwright MCP server: setup, tools and what we measured

Canonical: https://theagenticweekly.com/guides/playwright-mcp-server · Last verified: 2026-10-26 · Published: 2026-10-26 · Author: Agentic Weekly (operated independently from Texas, US) · Versions covered: @playwright/mcp 0.0.83 (the server prints Playwright 1.64.0-alpha-1790635538000); Node 20.19.2 and 24.22.1 · Evidence: Tested (smoke test, 2026-10-25, no LLM involved) · Tools: playwright-mcp

Checked 2026-10-26 by Agentic Weekly's editorial process: vendor docs re-read (the commands were run on 2026-10-25, not re-run on this date).

> Playwright MCP is Microsoft's MCP server that lets an AI agent drive a real browser. In our 2026-10-25 smoke test, version 0.0.83 started in 383 ms, listed 25 tools and navigated to a local page in 40.5 ms median, with no language model involved. We did not test clicking, typing or screenshots.

## What Playwright MCP is and who maintains it

Playwright MCP is an MCP server from Microsoft that exposes a browser to an AI agent. The README (read 2026-10-26) says it uses Playwright's accessibility tree rather than pixel input, and that it needs no vision model. The npm package `@playwright/mcp` lists the Apache-2.0 license and `node >=18` (npm registry, read 2026-10-26). The latest GitHub release when we read it was v0.0.83, published 2026-09-28.

New to the term? [What is an MCP server?](https://theagenticweekly.com/what-is/mcp-server) explains hosts, clients and servers. The README also states that Playwright MCP is not a security boundary, so treat any page the agent opens as untrusted input.

## Prerequisites

- Operating system and hardware we ran on: Linux x86_64 virtual machine (Debian 13), 8 vCPU, 15 GiB RAM, no GPU. Not run by us: macOS and Windows.
- Node.js: we ran 20.19.2 and 24.22.1 (both worked). The README says Node.js 18 or newer; we did not run Node 18.
- A browser: the package does not bundle one. We used the machine's existing Google Chrome at `/usr/bin/google-chrome`.
- Accounts and keys: none. Network: npm registry access to install.
- A model is not needed to start the server. Our measurements used a small Python client written with the official MCP Python SDK 2.3.0, with no language model involved.

## Step 1: Install the package

Install `@playwright/mcp` with npm. Our run resolved version 0.0.83; the latest version may differ when you read this.

Command (as logged)

```
npm install --no-audit --no-fund --cache /tmp/npmcache @playwright/mcp
```

Expected result (from the log notes)

```
Resolved 0.0.83; 19 MB in 3 packages.
Install time: 1.3 s on Node 20.19.2, 1.0 s on Node 24.22.1 (cold npm cache).
```

The small size is because no browser is downloaded. The server binary is `node_modules/.bin/playwright-mcp`.

Step evidence: Tested (npm install on both Node versions, 2026-10-25; log: [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp)).

## Step 2: Start the server in headless Chrome

Point the server at an installed Chrome and run it without a window. These are the exact flags in our log; each is explained in the flags table below.

Command (as logged)

```
node node_modules/.bin/playwright-mcp --headless --isolated --browser chrome --executable-path /usr/bin/google-chrome --no-sandbox
```

Expected result (what our client saw during the handshake)

```
server: Playwright 1.64.0-alpha-1790635538000
protocol: 2025-11-25
cold start (spawn to initialize result): 383 ms
```

The server speaks MCP over stdio, so you normally let your MCP client launch it rather than running it by hand. Remove `--no-sandbox` unless you are root or in a container (see Troubleshooting).

Step evidence: Tested (start over stdio with these flags, 2026-10-25; log: [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp)).

## Step 3: Connect it to an MCP client

These are the setup lines the README gives for popular clients (read 2026-10-26). We did not run any of them; our own test launched the server from a script.

Table: Setup by client, from the Playwright MCP README

| Client | Command or config | Source and date | Run by us? |
|---|---|---|---|
| Claude Code | `claude mcp add playwright npx @playwright/mcp@latest` | [README](https://github.com/microsoft/playwright-mcp), read 2026-10-26 | No |
| VS Code | `code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'` | [README](https://github.com/microsoft/playwright-mcp), read 2026-10-26 | No |
| Cursor | Cursor Settings, MCP, Add new MCP Server, type `command`, command `npx @playwright/mcp@latest` | [README](https://github.com/microsoft/playwright-mcp), read 2026-10-26 | No |
| Claude Desktop and most others | The README's "standard config": an `mcpServers` entry named `playwright` with `"command": "npx"` and `"args": ["@playwright/mcp@latest"]` | [README](https://github.com/microsoft/playwright-mcp), read 2026-10-26 | No |

To pass flags from Claude Code, the Claude Code docs say everything after `--` goes to the server untouched, so the shape is `claude mcp add playwright -- npx @playwright/mcp@latest --headless`. That line combines the two documents and we have not run it. For other Claude Code options see [Add an MCP server to Claude Code](https://theagenticweekly.com/guides/add-mcp-server-to-claude-code).

Step evidence: Reported (not run by us). Source: https://github.com/microsoft/playwright-mcp and https://code.claude.com/docs/en/mcp, read 2026-10-26.

## Step 4: See what the server exposes

In our run `tools/list` returned 25 tools in 10.1 ms. The README also documents extra tool groups that are switched on with `--caps` (for example vision, pdf, devtools and testing); we did not enable any, so 25 is the default set with the flags above and can change by version.

Tool names printed by tools/list in the same run

```
browser_close, browser_resize, browser_console_messages, browser_handle_dialog, browser_emulate_media, browser_evaluate, browser_file_upload, browser_drop, browser_find, browser_fill_form, browser_press_key, browser_type, browser_navigate, browser_navigate_back, browser_network_requests, browser_network_request, browser_run_code_unsafe, browser_take_screenshot, browser_snapshot, browser_click, browser_drag, browser_hover, browser_select_option, browser_tabs, browser_wait_for
```

The tool count matters because every tool schema takes space in a model's context window. We did not measure that cost.

Step evidence: Tested (tool count and timing, 2026-10-25; log: [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp)).

## Step 5: Make one call and read the result

We timed `browser_navigate` to a local fixture page served on 127.0.0.1. Ten sequential calls gave a median of 40.5 ms and a 95th percentile of 51.8 ms.

Output of one timed call (first 300 characters, from the log)

```
browser_navigate({"url": "http://127.0.0.1:8099/test.html"})
### Ran Playwright code
```js
await page.goto('http://127.0.0.1:8099/test.html');
```
### Page
- Page URL: http://127.0.0.1:8099/test.html
- Page Title: Fixture page
### Snapshot
- [Snapshot](.playwright-mcp/page-2026-10-26T03-39-23-508Z.yml)
```

The result carries the page title and a reference to a saved accessibility snapshot. That is a protocol and process timing for a tiny local page on a shared machine, not a measure of real-world page loads.

Step evidence: Tested (10 calls to browser_navigate, 2026-10-25; log: [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp)).

## Flags that matter

Table: Playwright MCP flags: what the README says and whether our run used them

| Flag | What the README says | Used in our run |
|---|---|---|
| `--headless` | Run the browser in headless mode; the default is headed. | Yes |
| `--isolated` | Keep the browser profile in memory and do not save it to disk. The README says concurrent clients sharing a persistent profile conflict, and suggests `--isolated` or a distinct `--user-data-dir` for parallel clients. | Yes |
| `--browser <browser>` | Browser or Chrome channel to use; possible values are chrome, firefox, webkit and msedge. | Yes (chrome) |
| `--executable-path <path>` | Path to the browser executable. | Yes (`/usr/bin/google-chrome`) |
| `--no-sandbox` | Disable the sandbox for all process types that are normally sandboxed. | Yes (we ran as root on a VM) |

Flag descriptions are quoted in substance from the [README](https://github.com/microsoft/playwright-mcp), read 2026-10-26. We only list flags that appear in the README and in our log; the README documents many more.

## What we tested

Evidence: Tested (smoke test, 2026-10-25, no LLM involved) for the steps marked Tested; Reported (not run by us) for client setup.

- What we ran: the install and start commands above, then a small Python client (official MCP Python SDK 2.3.0) over stdio that timed the handshake, one `tools/list` and 10 sequential `browser_navigate` calls. Server string printed: Playwright 1.64.0-alpha-1790635538000 (npm package 0.0.83). Run on 2026-10-25 at 22:39 CDT (America/Chicago).
- Environment: Linux x86_64 virtual machine (Debian 13), 8 vCPU, 15 GiB RAM, no GPU, shared with other jobs.
- Model: no language model involved.
- Full test log: [Playwright MCP test log](https://theagenticweekly.com/tests/playwright-mcp).
- Reported, from the README and Claude Code docs, not run by us: the client setup lines in Step 3 and the flag descriptions.
- Not tested: remote (HTTP) transport, authentication and concurrent clients; large payloads; clicking, typing, screenshots and snapshot-based element selection (only navigation was timed); any model driving the server; answer quality; Node 18.

Table: Evidence by step

| Step | Evidence | Covered by |
|---|---|---|
| 1 Install | Tested | [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp) |
| 2 Start with flags | Tested | [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp) |
| 3 Connect a client | Reported | [README](https://github.com/microsoft/playwright-mcp), read 2026-10-26 |
| 4 List tools | Tested | [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp) |
| 5 One navigate call | Tested | [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp) |

This is a smoke test, not a benchmark: one client, one tiny local page, one shared machine. A single run per Node version was used for install; the latency run used 10 calls.

## Troubleshooting

Table: Playwright MCP problems and fixes

| Symptom | Likely cause | Fix | Source |
|---|---|---|---|
| Chrome will not start as root or in a container | Chrome's sandbox needs privileges that root or a container lacks | Pass `--no-sandbox`. Do not do this on a machine that browses untrusted pages. | Gotcha noted in our log 2026-10-25; we passed the flag and did not record the failure without it, [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp) |
| The server reports `Playwright 1.64.0-alpha-...` but you installed 0.0.83 | The package version and the Playwright build it embeds are different numbers | Nothing to fix. Quote both when you report a problem. | Seen by us 2026-10-25, [/tests/playwright-mcp](https://theagenticweekly.com/tests/playwright-mcp) |
| Two clients fight over one browser profile | A persistent profile can be used by only one browser instance at a time | Start each extra client with `--isolated` or a distinct `--user-data-dir`. | [README](https://github.com/microsoft/playwright-mcp), read 2026-10-26 |
| The client cannot find the server | The client was configured with a command that is not on its PATH | Use the full path to `npx` or to `node_modules/.bin/playwright-mcp` in the client config. | Not reproduced by us; general MCP client behaviour, check your client's docs |

The last row has no vendor source, so treat it as a hint only.

## Playwright MCP vs Chrome DevTools MCP

Both servers drive Chrome, but they expose different tools and we timed different calls. The comparison page covers the rest: [Playwright MCP vs Chrome DevTools MCP](https://theagenticweekly.com/compare/playwright-mcp-vs-chrome-devtools-mcp). For the agent-side alternative see [Browser Use vs Playwright MCP](https://theagenticweekly.com/compare/browser-use-vs-playwright-mcp).

Table: Playwright MCP and Chrome DevTools MCP in our 2026-10-25 runs

| Attribute | Playwright MCP | Chrome DevTools MCP |
|---|---|---|
| Tools listed | 25 | 32 |
| Call we timed | browser_navigate, 10 calls, median 40.5 ms | new_page, 10 calls, median 136.6 ms |
| Evidence label | Tested (smoke test, 2026-10-25) | Tested (smoke test, 2026-10-25) |

The two timings are for different calls and are not comparable. Logs: [Playwright MCP](https://theagenticweekly.com/tests/playwright-mcp) and [Chrome DevTools MCP](https://theagenticweekly.com/tests/chrome-devtools-mcp).

## Related tools

- [Playwright MCP](https://theagenticweekly.com/tools/playwright-mcp): Microsoft's MCP server that lets agents drive a browser with Playwright. Tested (smoke test, 2026-10-25, no language model involved).

## FAQ

### How do I install the Playwright MCP server?

Run npm install @playwright/mcp. On 2026-10-25 that resolved version 0.0.83 (19 MB, 3 packages) in about a second on Node 20.19.2 and 24.22.1. A browser is not bundled, so we pointed it at an installed Google Chrome with --executable-path.

### How many tools does Playwright MCP have?

Our tools/list call on 2026-10-25 returned 25 tools for version 0.0.83 with the flags in this guide. The README documents extra groups behind the --caps flag, and the count can change by version.

### Does Playwright MCP work with a local model?

We timed the server without a language model; we have not yet measured a local model driving it. The server exposes 25 tool schemas, which is a lot of context for a small model, but we did not test that.

### Is Playwright MCP free?

The npm package lists the Apache-2.0 license (npm registry, read 2026-10-26), so the server itself is open source. Costs can come from the model or services you connect it to; we did not check any pricing.

### Do I need --no-sandbox?

We passed it because we ran as root on a virtual machine, and our log notes Chrome needs it there. It disables Chrome's sandbox, so do not use it on a machine that opens untrusted pages. As a normal user you may not need it; we did not test that.

### Have you tested Playwright MCP?

Yes, partly. On 2026-10-25 we ran a no-model smoke test: install, start, tools/list (25 tools) and 10 browser_navigate calls. We did not test clicking, typing, screenshots, remote transport or any model driving it. Client setup is from the README.

## Sources

- [Playwright MCP README and repository (Microsoft)](https://github.com/microsoft/playwright-mcp) (fetched 2026-10-26)
- [@playwright/mcp on the npm registry](https://www.npmjs.com/package/@playwright/mcp) (fetched 2026-10-26)
- [Playwright MCP v0.0.83 release (GitHub)](https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.83) (fetched 2026-10-26)
- [Claude Code MCP docs](https://code.claude.com/docs/en/mcp) (fetched 2026-10-26)

## Related

- [Test log: Playwright MCP](https://theagenticweekly.com/tests/playwright-mcp)
- [Playwright MCP facts and sources](https://theagenticweekly.com/tools/playwright-mcp)
- [Playwright MCP vs Chrome DevTools MCP](https://theagenticweekly.com/compare/playwright-mcp-vs-chrome-devtools-mcp)
- [Browser Use vs Playwright MCP](https://theagenticweekly.com/compare/browser-use-vs-playwright-mcp)
- [GitHub MCP Server vs Playwright MCP](https://theagenticweekly.com/compare/github-mcp-server-vs-playwright-mcp)
- [Best MCP servers](https://theagenticweekly.com/best/mcp-servers)
- [What is an MCP server?](https://theagenticweekly.com/what-is/mcp-server)
- [Study: MCP server startup and call latency](https://theagenticweekly.com/research/mcp-servers-latency-and-failures)
- [Guide: add an MCP server to Claude Code](https://theagenticweekly.com/guides/add-mcp-server-to-claude-code)

## Changelog

- 2026-10-26: First published. README, npm registry and release page read on this date; commands come from the 2026-10-25 test log and were not re-run.

## How to cite

Agentic Weekly, "Playwright MCP server: setup, tools and what we measured", last updated 2026-10-26, https://theagenticweekly.com/guides/playwright-mcp-server