# playwright-triage Adopt this skill: https://proskills.md/skills/other/microsoft-playwright-mcp-claude-skills-playwright-triage Page: https://proskills.md/skills/other/microsoft-playwright-mcp-claude-skills-playwright-triage This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required. ## File: .claude/skills/playwright-triage/SKILL.md size: 6750 sha: c524e8cb3938c38735c10f091714381a327548cb upstream: https://github.com/microsoft/playwright-mcp/blob/main/.claude/skills/playwright-triage/SKILL.md ````text --- name: playwright-triage description: Triage and fix one microsoft/playwright-mcp issue, or do a maintainer's task, unattended inside the Issue triage GitHub Actions workflow (.github/workflows/triage.yml), which a needs-triage, needs-triage-mac or needs-triage-win label starts, or a maintainer starts by hand with an issue, a task or both. Reproduces the issue on the runner, then leaves a verified fix proposal for the workflow to open as a draft PR, in this repo or in microsoft/playwright where the source of the MCP server is, or an investigation note for it to post on the issue. Only for that workflow. --- # Playwright MCP Issue Triage You run unattended in the [Issue triage](../../../.github/workflows/triage.yml) workflow of `microsoft/playwright-mcp`. First read the shared guide, `$AGENT_GUIDES_DIR/triage.md`, a copy of [microsoft/playwright/.github/actions/run-agent/guides/triage.md](https://github.com/microsoft/playwright/blob/main/.github/actions/run-agent/guides/triage.md), and then [CLAUDE.md](../../../CLAUDE.md), both in full. The guide says how to triage an issue in any Playwright repo. CLAUDE.md says how to build, test and lint this one. This file covers what neither has: where the code is, the checkouts, how to run a published version, and the outcome that this repo adds, a fix in `microsoft/playwright`. ## Where the code is This repo is the npm package `@playwright/mcp`: `cli.js`, `index.js`, the types, the README, the Dockerfile and some tests of the packaged server. `package.json` pins the alpha of `playwright` and `playwright-core` that the package runs. The MCP server is in `microsoft/playwright`, in `packages/playwright-core/src/tools/`: `mcp/` has the server, its config and its command line options, and `backend/` has the tools. Most bugs and most feature requests are fixed there. Fix a bug here only when the cause is in a file that this repo owns. These files are copies or outputs of upstream code, so their fix is upstream too: - `config.d.ts`: `roll.js` copies it from `packages/playwright-core/src/tools/mcp/config.d.ts`. - The tools and options in `README.md`: `npm run lint` generates them from the tools. ## The checkouts `$REPO_DIR` is the checkout of `microsoft/playwright-mcp` that the guide describes. `npm ci` ran in it, and the browsers of the pinned version are installed. The `chrome` and `msedge` projects use Google Chrome and Microsoft Edge from the runner image. When one is missing, install it with `npx playwright install chrome msedge`. The clone is shallow: run `git fetch --unshallow --tags origin` in it before you need its history. `$PLAYWRIGHT_DIR` is a clone of `microsoft/playwright` at the tip of `main`, next to `$REPO_DIR`. `npm ci` and `npm run build` ran in it, and Chromium, Firefox and WebKit are installed. It is tip-of-tree for this repo: reproduce there, as a test in its `tests/mcp/`. Read its `AGENTS.md` in full before you write that test. It says how to build, test and lint it, and which fixtures the MCP tests use. The clone has the full history, without file contents until git needs them, so `git log` and `git tag --contains` work there. The pinned version is older than tip-of-tree. `npm view playwright-core@ gitHead` prints the upstream commit that an alpha was built from. ## Fix in microsoft/playwright When the fix is in `$PLAYWRIGHT_DIR`, follow the Fix section of the guide there, in place of `$REPO_DIR`: create the branch `fix-` from `main` in `$PLAYWRIGHT_DIR`, put the regression test in its `tests/mcp/`, build and lint as its `AGENTS.md` says, and commit in its convention, for example `fix(mcp): ...`. Then leave the proposal in `$OUTPUT_DIR/upstream-fix/` in place of `$OUTPUT_DIR/fix/`: - `fix.patch`: the output of `git diff --binary main HEAD` in `$PLAYWRIGHT_DIR`. - `pr-body.md`: as the guide says. The `Fixes` line has the full URL of the issue, `Fixes https://github.com/microsoft/playwright-mcp/issues/`, so that the PR closes the issue in this repo. Add the `pull-request` call for `microsoft/playwright` last, as the guide says: ```json { "call": "pull-request", "repo": "microsoft/playwright", "branch": "triage/playwright-mcp-/-", "title": "fix(mcp): description", "patch": "upstream-fix/fix.patch", "bodyFile": "upstream-fix/pr-body.md", "commitBody": "Fixes: https://github.com/microsoft/playwright-mcp/issues/" } ``` The publish job checks out `microsoft/playwright` at the commit of `$PLAYWRIGHT_DIR` and opens the draft PR there. The revision workflow of that repo addresses the review. Make one `pull-request` call: in this repo or in `microsoft/playwright`, not both. Do not change `package.json` here to pick up the fix. It reaches `@playwright/mcp` with the next roll. **Check the linked PRs in both repos.** A PR in `microsoft/playwright` links this issue with its full URL or as `microsoft/playwright-mcp#`. Search there too: `repo:microsoft/playwright is:pr "playwright-mcp/issues/"` and `repo:microsoft/playwright is:pr "playwright-mcp#"`. A PR there from the team or from `microsoft-playwright-automation` is a team PR. Verify a PR there in `$PLAYWRIGHT_DIR`. **Already fixed** means that tip-of-tree passes and the pinned version fails. The fix reaches users with the next roll. Find the upstream PR with `git -C $PLAYWRIGHT_DIR log ..main -- packages/playwright-core/src/tools`, and name it in the note. ## Published versions To run a published version, for example the version of the reporter or to bisect, create `$SCRATCH_DIR/playwright-mcp-//` and run there: ```bash npm init -y npm i @playwright/mcp@ @modelcontextprotocol/sdk npx playwright install chromium firefox webkit ``` The fixtures of the repo are not available there. Write the condensed repro as a plain script in that directory. It starts `node_modules/@playwright/mcp/cli.js --headless` with the `StdioClientTransport` of the SDK, as `createTransport()` in `tests/fixtures.ts` does, and calls the tools with `client.callTool()`. Serve the page from a `data:` URL or from `http.createServer()` in the script. `npm view @playwright/mcp@ dependencies.playwright-core` prints the alpha of a release. Match a regression to upstream commits with `git -C $PLAYWRIGHT_DIR log .. -- packages/playwright-core/src/tools`. ## PRs from third parties Do not run a PR in this repo that changes `package.json`, `package-lock.json`, `roll.js`, `update-readme.js`, `utils/`, `Dockerfile`, `.devcontainer/`, `.github/`, `.azure-pipelines/` or `.claude/`. For a PR in `microsoft/playwright`, the list in `$PLAYWRIGHT_DIR/.claude/skills/playwright-triage/SKILL.md` applies. ```` ## File: README.md upstream: https://github.com/microsoft/playwright-mcp/blob/main/README.md ````text ## Playwright MCP A Model Context Protocol (MCP) server that provides browser automation capabilities using [Playwright](https://playwright.dev). This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models. ### Playwright MCP vs Playwright CLI This package provides MCP interface into Playwright. If you are using a **coding agent**, you might benefit from using the [CLI+SKILLS](https://github.com/microsoft/playwright-cli) instead. - **CLI**: Modern **coding agents** increasingly favor CLI–based workflows exposed as SKILLs over MCP because CLI invocations are more token-efficient: they avoid loading large tool schemas and verbose accessibility trees into the model context, allowing agents to act through concise, purpose-built commands. This makes CLI + SKILLs better suited for high-throughput coding agents that must balance browser automation with large codebases, tests, and reasoning within limited context windows.
**Learn more about [Playwright CLI with SKILLS](https://github.com/microsoft/playwright-cli)**. - **MCP**: MCP remains relevant for specialized agentic loops that benefit from persistent state, rich introspection, and iterative reasoning over page structure, such as exploratory automation, self-healing tests, or long-running autonomous workflows where maintaining continuous browser context outweighs token cost concerns. ### Key Features - **Fast and lightweight**. Uses Playwright's accessibility tree, not pixel-based input. - **LLM-friendly**. No vision models needed, operates purely on structured data. - **Deterministic tool application**. Avoids ambiguity common with screenshot-based approaches. ### Requirements - Node.js 18 or newer - VS Code, Cursor, Windsurf, Claude Desktop, Goose, Grok, Junie or any other MCP client ### Getting started First, install the Playwright MCP server with your client. **Standard config** works in most of the tools: ```js { "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest" ] } } } ``` [Install in VS Code](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [Install in VS Code Insiders](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
Amp Add via the Amp VS Code extension settings screen or by updating your settings.json file: ```json "amp.mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest" ] } } ``` **Amp CLI Setup:** Add via the `amp mcp add` command below ```bash amp mcp add playwright -- npx @playwright/mcp@latest ```
Antigravity Add via the Antigravity settings or by updating your configuration file: ```json { "mcpServers": { "playwright": { "command": "npx", "args": [ "@playwright/mcp@latest" ] } } } ```
Claude Code Use the Claude Code CLI to add the Playwright MCP server: ```bash claude mcp add playwright npx @playwright/mcp@latest ```
Claude Desktop Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.
Cline Follow the instruction in the section [Configuring MCP Servers](https://docs.cline.bot/mcp/configuring-mcp-servers) **Example: Local Setup** Add the following to your [`cline_mcp_settings.json`](https://docs.cline.bot/mcp/configuring-mcp-servers#editing-mcp-settings-files) file: ```json { "mcpServers": { "playwright": { "type": "stdio", "command": "npx", "timeout": 30, "args": [ "-y", "@playwright/mcp@latest" ], "disabled": false } } } ```
Codex Use the Codex CLI to add the Playwright MCP server: ```bash codex mcp add playwright npx "@playwright/mcp@latest" ``` Alternatively, create or edit the configuration file `~/.codex/config.toml` and add: ```toml [mcp_servers.playwright] command = "npx" args = ["@playwright/mcp@latest"] ``` For more information, see the [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers).
Copilot Use the Copilot CLI to interactively add the Playwright MCP server: ```bash /mcp add ``` Alternatively, create or edit the configuration file `~/.copilot/mcp-config.json` and add: ```json { "mcpServers": { "playwright": { "type": "local", "command": "npx", "tools": [ "*" ], "args": [ "@playwright/mcp@latest" ] } } } ``` For more information, see the [Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli).
Cursor #### Click the button to install: [Install in Cursor](https://cursor.com/en/install-mcp?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D) #### Or install manually: Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx @playwright/mcp@latest`. You can also verify config or add command like arguments via clicking `Edit`.
Factory Use the Factory CLI to add the Playwright MCP server: ```bash droid mcp add playwright "npx @playwright/mcp@latest" ``` Alternatively, type `/mcp` within Factory droid to open an interactive UI for managing MCP servers. For more information, see the [Factory MCP documentation](https://docs.factory.ai/cli/configuration/mcp).
Gemini CLI Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use the standard config above.
Goose #### Click the button to install: [![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=%40playwright%2Fmcp%40latest&id=playwright&name=Playwright&description=Interact%20with%20web%20pages%20through%20structured%20accessibility%20snapshots%20using%20Playwright) #### Or install manually: Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx @playwright/mcp`. Click "Add Extension".
Grok Use the Grok CLI to add the Playwright MCP server: ```bash grok mcp add playwright -- npx @playwright/mcp@latest ``` Alternatively, create or edit the configuration file `~/.grok/config.toml` and add: ```toml [mcp_servers.playwright] command = "npx" args = ["@playwright/mcp@latest"] ``` For more information, see the [Grok MCP documentation](https://docs.x.ai/build/features/mcp-servers).
Junie To add the Playwright MCP server in Junie CLI: 1. Type `/mcp` 2. Press `Ctrl+A` to add a new MCP server 3. Select **Playwright** from the list Alternativel ````