# Playwright MCP

Canonical: https://cqbase.net/en/entry/playwright-mcp
Chinese: https://cqbase.net/zh/entry/playwright-mcp
English: https://cqbase.net/en/entry/playwright-mcp

> Microsoft’s Playwright MCP server, so an agent can drive a browser.

microsoft/playwright-mcp is Apache-2.0 and published as the npm package @playwright/mcp. An MCP client can open pages, click, and read results through Playwright. That is useful when a coding task depends on reproducing a UI flow.

Try it first on a public test page or a local server you run. A logged-in session is a credential. Keep that scope small.

## What problem it solves

Playwright MCP is Microsoft’s official MCP server for driving a browser with Playwright. It locates elements mainly through the page’s accessibility snapshot. Official docs say common navigation, clicking, and typing can work without a vision model.

The repository README also notes that some coding agents now prefer the Playwright CLI plus skills, because commands usually cost less context. MCP is still a good fit when you want a persistent browser, rich inspection, and repeated reasoning over page structure. Those are different products. This page covers only the MCP server.

## Who it is for

It is for people who already use VS Code, Cursor, Claude Code, Claude Desktop, or another MCP client, and who want an agent to open and operate a real page. The project is open source under Apache-2.0, and the official getting-started config does not ask for an API key.

The Node.js requirement is not identical across official sources. The repository README says Node.js 18 or newer. Playwright’s MCP documentation page says Node.js 20 or newer. This page does not invent a single number; install against the source you are following, and check `node -v` on your machine.

Official docs also say Playwright MCP is **not** a security boundary. The agent can see and operate the pages it controls. Do not attach it casually to a signed-in session that holds secrets.

## How to install it

Checked on 15 November 2026 (Asia/Shanghai) against the [repository README](https://github.com/microsoft/playwright-mcp) and the [Playwright MCP docs](https://playwright.dev/docs/getting-started-mcp). Most clients accept this standard config:

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

In Cursor, go to Cursor Settings → MCP → Add new MCP Server, choose the command type, and use `npx @playwright/mcp@latest`.

In Claude Code, run this in your terminal:

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

In VS Code, official docs also show:

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

Core tools are enabled by default, including `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, and `browser_take_screenshot`. Extra groups such as network, storage, testing, vision, or PDF are turned on with `--caps`, for example `--caps=vision,pdf,devtools`. The browser is headed by default; pass `--headless` to hide it. A persistent profile can be used by only one browser instance at a time. For parallel clients, pass `--isolated` or give each one a distinct `--user-data-dir`.

## A worked example

The prompt below is a check written for this page, not a canned official phrase. It was not run in this review, so the page does not invent the page structure or a screenshot.

1. Finish the install above and confirm Playwright tools are visible in your client.
2. Send: `Open https://playwright.dev, take an accessibility snapshot, and tell me the main heading and the first few navigation links.`
3. Based on official tool descriptions, the agent should usually call `browser_navigate`, then `browser_snapshot` to read the accessibility tree, rather than starting from a screenshot. Screenshots exist in the core tool set, but the getting-started material emphasizes snapshots.
4. Check the heading and navigation against the page you see. Official docs note that the snapshot is the accessibility tree, not the full HTML.

## Common pitfalls

- The browser profile is already in use. Official docs say a persistent profile can belong to only one instance at a time. Extra clients should use `--isolated` or a separate user-data directory. [Issue #769](https://github.com/microsoft/playwright-mcp/issues/769) and [issue #942](https://github.com/microsoft/playwright-mcp/issues/942) both report `Browser is already in use`.
- Chrome is not found on Windows. [Issue #13](https://github.com/microsoft/playwright-mcp/issues/13) reported `chrome' is not found`. Confirm a browser is installed, and follow the current README for install or channel options rather than an outdated third-party step.
- Treating the server as a sandbox. The README security section says it is not a security boundary, and points to MCP security guidance. Be careful with pages that already hold a login or secrets.
- Node.js version mismatches. If the server fails to start, check whether you followed the README’s 18+ requirement or the docs site’s 20+ requirement, then look at the Node version on your machine. Do not average the two.

## FAQ

### Do I need an API key or a paid Playwright account?

The official getting-started config does not ask for a Playwright API key. You need a Node.js version that matches the docs you follow, and an MCP client. The client itself, such as Claude Code, may have its own account requirements.

### Should I use MCP or the Playwright CLI?

The README draws a clear line. CLI plus skills is usually more token-efficient. MCP is better when you want persistent browser state and repeated inspection. If your agent already prefers the CLI, see [playwright-cli](https://github.com/microsoft/playwright-cli) and do not mix the two command sets.

### Does it open a visible window by default?

Yes. Official docs say the browser is headed by default. Pass `--headless` to run it in the background.

### Why are some tools missing?

Only core tools are enabled at first. Network, storage, testing, vision, pdf, and devtools have to be turned on with `--caps`. Do not assume every tool is present on a fresh install.

### Can I run two clients at once?

Yes, but do not share one persistent profile. Official docs recommend `--isolated` for extra instances, or a different `--user-data-dir` for each.

## Sources and license

[microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) is licensed under Apache-2.0. This page follows the README and the [Playwright MCP getting-started docs](https://playwright.dev/docs/getting-started-mcp) as of 15 November 2026, rewritten for CQBase — Context & Query Base. If the install commands or the Node.js requirement change, follow those official pages.

## Catalog record

- Author: microsoft
- License: Apache-2.0
- Source: https://github.com/microsoft/playwright-mcp
- Added: 2026-11-15
- GitHub stars: 39660 (captured 2026-11-15)

