A Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models. This package provides MCP interface into Playwright. If you are using a coding agent, you might benefit from using the CLI+SKILLS instead. -
Add this skill
npx mdskills install microsoft/playwright-mcpWell-documented MCP server for browser automation with comprehensive setup instructions and security controls
1## Playwright MCP23A 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.45### Playwright MCP vs Playwright CLI67This 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.89- **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.<br>**Learn more about [Playwright CLI with SKILLS](https://github.com/microsoft/playwright-cli)**.1011- **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.1213### Key Features1415- **Fast and lightweight**. Uses Playwright's accessibility tree, not pixel-based input.16- **LLM-friendly**. No vision models needed, operates purely on structured data.17- **Deterministic tool application**. Avoids ambiguity common with screenshot-based approaches.1819### Requirements20- Node.js 18 or newer21- VS Code, Cursor, Windsurf, Claude Desktop, Goose or any other MCP client2223<!--24// Generate using:25node utils/generate-links.js26-->2728### Getting started2930First, install the Playwright MCP server with your client.3132**Standard config** works in most of the tools:3334```js35{36 "mcpServers": {37 "playwright": {38 "command": "npx",39 "args": [40 "@playwright/mcp@latest"41 ]42 }43 }44}45```4647[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="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) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](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)4849<details>50<summary>Amp</summary>5152Add via the Amp VS Code extension settings screen or by updating your settings.json file:5354```json55"amp.mcpServers": {56 "playwright": {57 "command": "npx",58 "args": [59 "@playwright/mcp@latest"60 ]61 }62}63```6465**Amp CLI Setup:**6667Add via the `amp mcp add`command below6869```bash70amp mcp add playwright -- npx @playwright/mcp@latest71```7273</details>7475<details>76<summary>Claude Code</summary>7778Use the Claude Code CLI to add the Playwright MCP server:7980```bash81claude mcp add playwright npx @playwright/mcp@latest82```83</details>8485<details>86<summary>Claude Desktop</summary>8788Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.8990</details>9192<details>93<summary>Cline</summary>9495Follow the instruction in the section [Configuring MCP Servers](https://docs.cline.bot/mcp/configuring-mcp-servers)9697**Example: Local Setup**9899Add the following to your [`cline_mcp_settings.json`](https://docs.cline.bot/mcp/configuring-mcp-servers#editing-mcp-settings-files) file:100101```json102{103 "mcpServers": {104 "playwright": {105 "type": "stdio",106 "command": "npx",107 "timeout": 30,108 "args": [109 "-y",110 "@playwright/mcp@latest"111 ],112 "disabled": false113 }114 }115}116```117118</details>119120<details>121<summary>Codex</summary>122123Use the Codex CLI to add the Playwright MCP server:124125```bash126codex mcp add playwright npx "@playwright/mcp@latest"127```128129Alternatively, create or edit the configuration file `~/.codex/config.toml` and add:130131```toml132[mcp_servers.playwright]133command = "npx"134args = ["@playwright/mcp@latest"]135```136137For more information, see the [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers).138139</details>140141<details>142<summary>Copilot</summary>143144Use the Copilot CLI to interactively add the Playwright MCP server:145146```bash147/mcp add148```149150Alternatively, create or edit the configuration file `~/.copilot/mcp-config.json` and add:151152```json153{154 "mcpServers": {155 "playwright": {156 "type": "local",157 "command": "npx",158 "tools": [159 "*"160 ],161 "args": [162 "@playwright/mcp@latest"163 ]164 }165 }166}167```168169For more information, see the [Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli).170171</details>172173<details>174<summary>Cursor</summary>175176#### Click the button to install:177178[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)179180#### Or install manually:181182Go 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`.183184</details>185186<details>187<summary>Factory</summary>188189Use the Factory CLI to add the Playwright MCP server:190191```bash192droid mcp add playwright "npx @playwright/mcp@latest"193```194195Alternatively, type `/mcp` within Factory droid to open an interactive UI for managing MCP servers.196197For more information, see the [Factory MCP documentation](https://docs.factory.ai/cli/configuration/mcp).198199</details>200201<details>202<summary>Gemini CLI</summary>203204Follow 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.205206</details>207208<details>209<summary>Goose</summary>210211#### Click the button to install:212213[](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)214215#### Or install manually:216217Go 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".218</details>219220<details>221<summary>Kiro</summary>222223Follow the MCP Servers [documentation](https://kiro.dev/docs/mcp/). For example in `.kiro/settings/mcp.json`:224225```json226{227 "mcpServers": {228 "playwright": {229 "command": "npx",230 "args": [231 "@playwright/mcp@latest"232 ]233 }234 }235}236```237</details>238239<details>240<summary>LM Studio</summary>241242#### Click the button to install:243244[](https://lmstudio.ai/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcGxheXdyaWdodC9tY3BAbGF0ZXN0Il19)245246#### Or install manually:247248Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.249</details>250251<details>252<summary>opencode</summary>253254Follow the MCP Servers [documentation](https://opencode.ai/docs/mcp-servers/). For example in `~/.config/opencode/opencode.json`:255256```json257{258 "$schema": "https://opencode.ai/config.json",259 "mcp": {260 "playwright": {261 "type": "local",262 "command": [263 "npx",264 "@playwright/mcp@latest"265 ],266 "enabled": true267 }268 }269}270271```272</details>273274<details>275<summary>Qodo Gen</summary>276277Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.278279Click <code>Save</code>.280</details>281282<details>283<summary>VS Code</summary>284285#### Click the button to install:286287[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="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) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](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)288289#### Or install manually:290291Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the Playwright MCP server using the VS Code CLI:292293```bash294# For VS Code295code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'296```297298After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.299</details>300301<details>302<summary>Warp</summary>303304Go to `Settings` -> `AI` -> `Manage MCP Servers` -> `+ Add` to [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). Use the standard config above.305306Alternatively, use the slash command `/add-mcp` in the Warp prompt and paste the standard config from above:307```js308{309 "mcpServers": {310 "playwright": {311 "command": "npx",312 "args": [313 "@playwright/mcp@latest"314 ]315 }316 }317}318```319320</details>321322<details>323<summary>Windsurf</summary>324325Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config above.326327</details>328329### Configuration330331Playwright MCP server supports following arguments. They can be provided in the JSON configuration above, as a part of the `"args"` list:332333<!--- Options generated by update-readme.js -->334335| Option | Description |336|--------|-------------|337| --allowed-hosts <hosts...> | comma-separated list of hosts this server is allowed to serve from. Defaults to the host the server is bound to. Pass '*' to disable the host check.<br>*env* `PLAYWRIGHT_MCP_ALLOWED_HOSTS` |338| --allowed-origins <origins> | semicolon-separated list of TRUSTED origins to allow the browser to request. Default is to allow all. Important: *does not* serve as a security boundary and *does not* affect redirects.<br>*env* `PLAYWRIGHT_MCP_ALLOWED_ORIGINS` |339| --allow-unrestricted-file-access | allow access to files outside of the workspace roots. Also allows unrestricted access to file:// URLs. By default access to file system is restricted to workspace root directories (or cwd if no roots are configured) only, and navigation to file:// URLs is blocked.<br>*env* `PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS` |340| --blocked-origins <origins> | semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed. Important: *does not* serve as a security boundary and *does not* affect redirects.<br>*env* `PLAYWRIGHT_MCP_BLOCKED_ORIGINS` |341| --block-service-workers | block service workers<br>*env* `PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS` |342| --browser <browser> | browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.<br>*env* `PLAYWRIGHT_MCP_BROWSER` |343| --caps <caps> | comma-separated list of additional capabilities to enable, possible values: vision, pdf, devtools.<br>*env* `PLAYWRIGHT_MCP_CAPS` |344| --cdp-endpoint <endpoint> | CDP endpoint to connect to.<br>*env* `PLAYWRIGHT_MCP_CDP_ENDPOINT` |345| --cdp-header <headers...> | CDP headers to send with the connect request, multiple can be specified.<br>*env* `PLAYWRIGHT_MCP_CDP_HEADER` |346| --cdp-timeout <timeout> | timeout in milliseconds for connecting to CDP endpoint, defaults to 30000ms<br>*env* `PLAYWRIGHT_MCP_CDP_TIMEOUT` |347| --codegen <lang> | specify the language to use for code generation, possible values: "typescript", "none". Default is "typescript".<br>*env* `PLAYWRIGHT_MCP_CODEGEN` |348| --config <path> | path to the configuration file.<br>*env* `PLAYWRIGHT_MCP_CONFIG` |349| --console-level <level> | level of console messages to return: "error", "warning", "info", "debug". Each level includes the messages of more severe levels.<br>*env* `PLAYWRIGHT_MCP_CONSOLE_LEVEL` |350| --device <device> | device to emulate, for example: "iPhone 15"<br>*env* `PLAYWRIGHT_MCP_DEVICE` |351| --executable-path <path> | path to the browser executable.<br>*env* `PLAYWRIGHT_MCP_EXECUTABLE_PATH` |352| --extension | Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.<br>*env* `PLAYWRIGHT_MCP_EXTENSION` |353| --grant-permissions <permissions...> | List of permissions to grant to the browser context, for example "geolocation", "clipboard-read", "clipboard-write".<br>*env* `PLAYWRIGHT_MCP_GRANT_PERMISSIONS` |354| --headless | run browser in headless mode, headed by default<br>*env* `PLAYWRIGHT_MCP_HEADLESS` |355| --host <host> | host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.<br>*env* `PLAYWRIGHT_MCP_HOST` |356| --ignore-https-errors | ignore https errors<br>*env* `PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS` |357| --init-page <path...> | path to TypeScript file to evaluate on Playwright page object<br>*env* `PLAYWRIGHT_MCP_INIT_PAGE` |358| --init-script <path...> | path to JavaScript file to add as an initialization script. The script will be evaluated in every page before any of the page's scripts. Can be specified multiple times.<br>*env* `PLAYWRIGHT_MCP_INIT_SCRIPT` |359| --isolated | keep the browser profile in memory, do not save it to disk.<br>*env* `PLAYWRIGHT_MCP_ISOLATED` |360| --image-responses <mode> | whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".<br>*env* `PLAYWRIGHT_MCP_IMAGE_RESPONSES` |361| --no-sandbox | disable the sandbox for all process types that are normally sandboxed.<br>*env* `PLAYWRIGHT_MCP_NO_SANDBOX` |362| --output-dir <path> | path to the directory for output files.<br>*env* `PLAYWRIGHT_MCP_OUTPUT_DIR` |363| --output-mode <mode> | whether to save snapshots, console messages, network logs to a file or to the standard output. Can be "file" or "stdout". Default is "stdout".<br>*env* `PLAYWRIGHT_MCP_OUTPUT_MODE` |364| --port <port> | port to listen on for SSE transport.<br>*env* `PLAYWRIGHT_MCP_PORT` |365| --proxy-bypass <bypass> | comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"<br>*env* `PLAYWRIGHT_MCP_PROXY_BYPASS` |366| --proxy-server <proxy> | specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"<br>*env* `PLAYWRIGHT_MCP_PROXY_SERVER` |367| --sandbox | enable the sandbox for all process types that are normally not sandboxed.<br>*env* `PLAYWRIGHT_MCP_SANDBOX` |368| --save-session | Whether to save the Playwright MCP session into the output directory.<br>*env* `PLAYWRIGHT_MCP_SAVE_SESSION` |369| --save-trace | Whether to save the Playwright Trace of the session into the output directory.<br>*env* `PLAYWRIGHT_MCP_SAVE_TRACE` |370| --save-video <size> | Whether to save the video of the session into the output directory. For example "--save-video=800x600"<br>*env* `PLAYWRIGHT_MCP_SAVE_VIDEO` |371| --secrets <path> | path to a file containing secrets in the dotenv format<br>*env* `PLAYWRIGHT_MCP_SECRETS` |372| --shared-browser-context | reuse the same browser context between all connected HTTP clients.<br>*env* `PLAYWRIGHT_MCP_SHARED_BROWSER_CONTEXT` |373| --snapshot-mode <mode> | when taking snapshots for responses, specifies the mode to use. Can be "incremental", "full", or "none". Default is incremental.<br>*env* `PLAYWRIGHT_MCP_SNAPSHOT_MODE` |374| --storage-state <path> | path to the storage state file for isolated sessions.<br>*env* `PLAYWRIGHT_MCP_STORAGE_STATE` |375| --test-id-attribute <attribute> | specify the attribute to use for test ids, defaults to "data-testid"<br>*env* `PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE` |376| --timeout-action <timeout> | specify action timeout in milliseconds, defaults to 5000ms<br>*env* `PLAYWRIGHT_MCP_TIMEOUT_ACTION` |377| --timeout-navigation <timeout> | specify navigation timeout in milliseconds, defaults to 60000ms<br>*env* `PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION` |378| --user-agent <ua string> | specify user agent string<br>*env* `PLAYWRIGHT_MCP_USER_AGENT` |379| --user-data-dir <path> | path to the user data directory. If not specified, a temporary directory will be created.<br>*env* `PLAYWRIGHT_MCP_USER_DATA_DIR` |380| --viewport-size <size> | specify browser viewport size in pixels, for example "1280x720"<br>*env* `PLAYWRIGHT_MCP_VIEWPORT_SIZE` |381382<!--- End of options generated section -->383384### User profile385386You can run Playwright MCP with persistent profile like a regular browser (default), in isolated contexts for testing sessions, or connect to your existing browser using the browser extension.387388**Persistent profile**389390All the logged in information will be stored in the persistent profile, you can delete it between sessions if you'd like to clear the offline state.391Persistent profile is located at the following locations and you can override it with the `--user-data-dir` argument.392393```bash394# Windows395%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile396397# macOS398- ~/Library/Caches/ms-playwright/mcp-{channel}-profile399400# Linux401- ~/.cache/ms-playwright/mcp-{channel}-profile402```403404**Isolated**405406In the isolated mode, each session is started in the isolated profile. Every time you ask MCP to close the browser,407the session is closed and all the storage state for this session is lost. You can provide initial storage state408to the browser via the config's `contextOptions` or via the `--storage-state` argument. Learn more about the storage409state [here](https://playwright.dev/docs/auth).410411```js412{413 "mcpServers": {414 "playwright": {415 "command": "npx",416 "args": [417 "@playwright/mcp@latest",418 "--isolated",419 "--storage-state={path/to/storage.json}"420 ]421 }422 }423}424```425426**Browser Extension**427428The Playwright MCP Chrome Extension allows you to connect to existing browser tabs and leverage your logged-in sessions and browser state. See [packages/extension/README.md](packages/extension/README.md) for installation and setup instructions.429430### Initial state431432There are multiple ways to provide the initial state to the browser context or a page.433434For the storage state, you can either:435- Start with a user data directory using the `--user-data-dir` argument. This will persist all browser data between the sessions.436- Start with a storage state file using the `--storage-state` argument. This will load cookies and local storage from the file into an isolated browser context.437438For the page state, you can use:439440- `--init-page` to point to a TypeScript file that will be evaluated on the Playwright page object. This allows you to run arbitrary code to set up the page.441442```ts443// init-page.ts444export default async ({ page }) => {445 await page.context().grantPermissions(['geolocation']);446 await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });447 await page.setViewportSize({ width: 1280, height: 720 });448};449```450451- `--init-script` to point to a JavaScript file that will be added as an initialization script. The script will be evaluated in every page before any of the page's scripts.452This is useful for overriding browser APIs or setting up the environment.453454```js455// init-script.js456window.isPlaywrightMCP = true;457```458459### Configuration file460461The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file462using the `--config` command line option:463464```bash465npx @playwright/mcp@latest --config path/to/config.json466```467468<details>469<summary>Configuration file schema</summary>470471<!--- Config generated by update-readme.js -->472473```typescript474{475 /**476 * The browser to use.477 */478 browser?: {479 /**480 * The type of browser to use.481 */482 browserName?: 'chromium' | 'firefox' | 'webkit';483484 /**485 * Keep the browser profile in memory, do not save it to disk.486 */487 isolated?: boolean;488489 /**490 * Path to a user data directory for browser profile persistence.491 * Temporary directory is created by default.492 */493 userDataDir?: string;494495 /**496 * Launch options passed to497 * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context498 *499 * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.500 */501 launchOptions?: playwright.LaunchOptions;502503 /**504 * Context options for the browser context.505 *506 * This is useful for settings options like `viewport`.507 */508 contextOptions?: playwright.BrowserContextOptions;509510 /**511 * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.512 */513 cdpEndpoint?: string;514515 /**516 * CDP headers to send with the connect request.517 */518 cdpHeaders?: Record<string, string>;519520 /**521 * Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.522 */523 cdpTimeout?: number;524525 /**526 * Remote endpoint to connect to an existing Playwright server.527 */528 remoteEndpoint?: string;529530 /**531 * Paths to TypeScript files to add as initialization scripts for Playwright page.532 */533 initPage?: string[];534535 /**536 * Paths to JavaScript files to add as initialization scripts.537 * The scripts will be evaluated in every page before any of the page's scripts.538 */539 initScript?: string[];540 },541542 /**543 * Connect to a running browser instance (Edge/Chrome only). If specified, `browser`544 * config is ignored.545 * Requires the "Playwright MCP Bridge" browser extension to be installed.546 */547 extension?: boolean;548549 server?: {550 /**551 * The port to listen on for SSE or MCP transport.552 */553 port?: number;554555 /**556 * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.557 */558 host?: string;559560 /**561 * The hosts this server is allowed to serve from. Defaults to the host server is bound to.562 * This is not for CORS, but rather for the DNS rebinding protection.563 */564 allowedHosts?: string[];565 },566567 /**568 * List of enabled tool capabilities. Possible values:569 * - 'core': Core browser automation features.570 * - 'pdf': PDF generation and manipulation.571 * - 'vision': Coordinate-based interactions.572 * - 'devtools': Developer tools features.573 */574 capabilities?: ToolCapability[];575576 /**577 * Whether to save the Playwright session into the output directory.578 */579 saveSession?: boolean;580581 /**582 * Whether to save the Playwright trace of the session into the output directory.583 */584 saveTrace?: boolean;585586 /**587 * If specified, saves the Playwright video of the session into the output directory.588 */589 saveVideo?: {590 width: number;591 height: number;592 };593594 /**595 * Reuse the same browser context between all connected HTTP clients.596 */597 sharedBrowserContext?: boolean;598599 /**600 * Secrets are used to prevent LLM from getting sensitive data while601 * automating scenarios such as authentication.602 * Prefer the browser.contextOptions.storageState over secrets file as a more secure alternative.603 */604 secrets?: Record<string, string>;605606 /**607 * The directory to save output files.608 */609 outputDir?: string;610611 /**612 * Whether to save snapshots, console messages, network logs and other session logs to a file or to the standard output. Defaults to "stdout".613 */614 outputMode?: 'file' | 'stdout';615616 console?: {617 /**618 * The level of console messages to return. Each level includes the messages of more severe levels. Defaults to "info".619 */620 level?: 'error' | 'warning' | 'info' | 'debug';621 },622623 network?: {624 /**625 * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.626 *627 * Supported formats:628 * - Full origin: `https://example.com:8080` - matches only that origin629 * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol630 */631 allowedOrigins?: string[];632633 /**634 * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.635 *636 * Supported formats:637 * - Full origin: `https://example.com:8080` - matches only that origin638 * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol639 */640 blockedOrigins?: string[];641 };642643 /**644 * Specify the attribute to use for test ids, defaults to "data-testid".645 */646 testIdAttribute?: string;647648 timeouts?: {649 /*650 * Configures default action timeout: https://playwright.dev/docs/api/class-page#page-set-default-timeout. Defaults to 5000ms.651 */652 action?: number;653654 /*655 * Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.656 */657 navigation?: number;658 };659660 /**661 * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.662 */663 imageResponses?: 'allow' | 'omit';664665 snapshot?: {666 /**667 * When taking snapshots for responses, specifies the mode to use.668 */669 mode?: 'incremental' | 'full' | 'none';670 };671672 /**673 * Whether to allow file uploads from anywhere on the file system.674 * By default (false), file uploads are restricted to paths within the MCP roots only.675 */676 allowUnrestrictedFileAccess?: boolean;677678 /**679 * Specify the language to use for code generation.680 */681 codegen?: 'typescript' | 'none';682}683```684685<!--- End of config generated section -->686687</details>688689### Standalone MCP server690691When running headed browser on system w/o display or from worker processes of the IDEs,692run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable HTTP transport.693694```bash695npx @playwright/mcp@latest --port 8931696```697698And then in MCP client config, set the `url` to the HTTP endpoint:699700```js701{702 "mcpServers": {703 "playwright": {704 "url": "http://localhost:8931/mcp"705 }706 }707}708```709710<details>711<summary><b>Docker</b></summary>712713**NOTE:** The Docker implementation only supports headless chromium at the moment.714715```js716{717 "mcpServers": {718 "playwright": {719 "command": "docker",720 "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]721 }722 }723}724```725726Or If you prefer to run the container as a long-lived service instead of letting the MCP client spawn it, use:727728```729docker run -d -i --rm --init --pull=always \730 --entrypoint node \731 --name playwright \732 -p 8931:8931 \733 mcr.microsoft.com/playwright/mcp \734 cli.js --headless --browser chromium --no-sandbox --port 8931735```736737The server will listen on host port **8931** and can be reached by any MCP client.738739You can build the Docker image yourself.740741```742docker build -t mcr.microsoft.com/playwright/mcp .743```744</details>745746<details>747<summary><b>Programmatic usage</b></summary>748749```js750import http from 'http';751752import { createConnection } from '@playwright/mcp';753import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';754755http.createServer(async (req, res) => {756 // ...757758 // Creates a headless Playwright MCP server with SSE transport759 const connection = await createConnection({ browser: { launchOptions: { headless: true } } });760 const transport = new SSEServerTransport('/messages', res);761 await connection.connect(transport);762763 // ...764});765```766</details>767768### Tools769770<!--- Tools generated by update-readme.js -->771772<details>773<summary><b>Core automation</b></summary>774775<!-- NOTE: This has been generated via update-readme.js -->776777- **browser_click**778 - Title: Click779 - Description: Perform click on a web page780 - Parameters:781 - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element782 - `ref` (string): Exact target element reference from the page snapshot783 - `doubleClick` (boolean, optional): Whether to perform a double click instead of a single click784 - `button` (string, optional): Button to click, defaults to left785 - `modifiers` (array, optional): Modifier keys to press786 - Read-only: **false**787788<!-- NOTE: This has been generated via update-readme.js -->789790- **browser_close**791 - Title: Close browser792 - Description: Close the page793 - Parameters: None794 - Read-only: **false**795796<!-- NOTE: This has been generated via update-readme.js -->797798- **browser_console_messages**799 - Title: Get console messages800 - Description: Returns all console messages801 - Parameters:802 - `level` (string): Level of the console messages to return. Each level includes the messages of more severe levels. Defaults to "info".803 - `filename` (string, optional): Filename to save the console messages to. If not provided, messages are returned as text.804 - Read-only: **true**805806<!-- NOTE: This has been generated via update-readme.js -->807808- **browser_drag**809 - Title: Drag mouse810 - Description: Perform drag and drop between two elements811 - Parameters:812 - `startElement` (string): Human-readable source element description used to obtain the permission to interact with the element813 - `startRef` (string): Exact source element reference from the page snapshot814 - `endElement` (string): Human-readable target element description used to obtain the permission to interact with the element815 - `endRef` (string): Exact target element reference from the page snapshot816 - Read-only: **false**817818<!-- NOTE: This has been generated via update-readme.js -->819820- **browser_evaluate**821 - Title: Evaluate JavaScript822 - Description: Evaluate JavaScript expression on page or element823 - Parameters:824 - `function` (string): () => { /* code */ } or (element) => { /* code */ } when element is provided825 - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element826 - `ref` (string, optional): Exact target element reference from the page snapshot827 - Read-only: **false**828829<!-- NOTE: This has been generated via update-readme.js -->830831- **browser_file_upload**832 - Title: Upload files833 - Description: Upload one or multiple files834 - Parameters:835 - `paths` (array, optional): The absolute paths to the files to upload. Can be single file or multiple files. If omitted, file chooser is cancelled.836 - Read-only: **false**837838<!-- NOTE: This has been generated via update-readme.js -->839840- **browser_fill_form**841 - Title: Fill form842 - Description: Fill multiple form fields843 - Parameters:844 - `fields` (array): Fields to fill in845 - Read-only: **false**846847<!-- NOTE: This has been generated via update-readme.js -->848849- **browser_handle_dialog**850 - Title: Handle a dialog851 - Description: Handle a dialog852 - Parameters:853 - `accept` (boolean): Whether to accept the dialog.854 - `promptText` (string, optional): The text of the prompt in case of a prompt dialog.855 - Read-only: **false**856857<!-- NOTE: This has been generated via update-readme.js -->858859- **browser_hover**860 - Title: Hover mouse861 - Description: Hover over element on page862 - Parameters:863 - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element864 - `ref` (string): Exact target element reference from the page snapshot865 - Read-only: **false**866867<!-- NOTE: This has been generated via update-readme.js -->868869- **browser_navigate**870 - Title: Navigate to a URL871 - Description: Navigate to a URL872 - Parameters:873 - `url` (string): The URL to navigate to874 - Read-only: **false**875876<!-- NOTE: This has been generated via update-readme.js -->877878- **browser_navigate_back**879 - Title: Go back880 - Description: Go back to the previous page in the history881 - Parameters: None882 - Read-only: **false**883884<!-- NOTE: This has been generated via update-readme.js -->885886- **browser_network_requests**887 - Title: List network requests888 - Description: Returns all network requests since loading the page889 - Parameters:890 - `includeStatic` (boolean): Whether to include successful static resources like images, fonts, scripts, etc. Defaults to false.891 - `filename` (string, optional): Filename to save the network requests to. If not provided, requests are returned as text.892 - Read-only: **true**893894<!-- NOTE: This has been generated via update-readme.js -->895896- **browser_press_key**897 - Title: Press a key898 - Description: Press a key on the keyboard899 - Parameters:900 - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`901 - Read-only: **false**902903<!-- NOTE: This has been generated via update-readme.js -->904905- **browser_resize**906 - Title: Resize browser window907 - Description: Resize the browser window908 - Parameters:909 - `width` (number): Width of the browser window910 - `height` (number): Height of the browser window911 - Read-only: **false**912913<!-- NOTE: This has been generated via update-readme.js -->914915- **browser_run_code**916 - Title: Run Playwright code917 - Description: Run Playwright code snippet918 - Parameters:919 - `code` (string): A JavaScript function containing Playwright code to execute. It will be invoked with a single argument, page, which you can use for any page interaction. For example: `async (page) => { await page.getByRole('button', { name: 'Submit' }).click(); return await page.title(); }`920 - Read-only: **false**921922<!-- NOTE: This has been generated via update-readme.js -->923924- **browser_select_option**925 - Title: Select option926 - Description: Select an option in a dropdown927 - Parameters:928 - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element929 - `ref` (string): Exact target element reference from the page snapshot930 - `values` (array): Array of values to select in the dropdown. This can be a single value or multiple values.931 - Read-only: **false**932933<!-- NOTE: This has been generated via update-readme.js -->934935- **browser_snapshot**936 - Title: Page snapshot937 - Description: Capture accessibility snapshot of the current page, this is better than screenshot938 - Parameters:939 - `filename` (string, optional): Save snapshot to markdown file instead of returning it in the response.940 - Read-only: **true**941942<!-- NOTE: This has been generated via update-readme.js -->943944- **browser_take_screenshot**945 - Title: Take a screenshot946 - Description: Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.947 - Parameters:948 - `type` (string): Image format for the screenshot. Default is png.949 - `filename` (string, optional): File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified. Prefer relative file names to stay within the output directory.950 - `element` (string, optional): Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.951 - `ref` (string, optional): Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.952 - `fullPage` (boolean, optional): When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.953 - Read-only: **true**954955<!-- NOTE: This has been generated via update-readme.js -->956957- **browser_type**958 - Title: Type text959 - Description: Type text into editable element960 - Parameters:961 - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element962 - `ref` (string): Exact target element reference from the page snapshot963 - `text` (string): Text to type into the element964 - `submit` (boolean, optional): Whether to submit entered text (press Enter after)965 - `slowly` (boolean, optional): Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.966 - Read-only: **false**967968<!-- NOTE: This has been generated via update-readme.js -->969970- **browser_wait_for**971 - Title: Wait for972 - Description: Wait for text to appear or disappear or a specified time to pass973 - Parameters:974 - `time` (number, optional): The time to wait in seconds975 - `text` (string, optional): The text to wait for976 - `textGone` (string, optional): The text to wait for to disappear977 - Read-only: **false**978979</details>980981<details>982<summary><b>Tab management</b></summary>983984<!-- NOTE: This has been generated via update-readme.js -->985986- **browser_tabs**987 - Title: Manage tabs988 - Description: List, create, close, or select a browser tab.989 - Parameters:990 - `action` (string): Operation to perform991 - `index` (number, optional): Tab index, used for close/select. If omitted for close, current tab is closed.992 - Read-only: **false**993994</details>995996<details>997<summary><b>Browser installation</b></summary>998999<!-- NOTE: This has been generated via update-readme.js -->10001001- **browser_install**1002 - Title: Install the browser specified in the config1003 - Description: Install the browser specified in the config. Call this if you get an error about the browser not being installed.1004 - Parameters: None1005 - Read-only: **false**10061007</details>10081009<details>1010<summary><b>Coordinate-based (opt-in via --caps=vision)</b></summary>10111012<!-- NOTE: This has been generated via update-readme.js -->10131014- **browser_mouse_click_xy**1015 - Title: Click1016 - Description: Click left mouse button at a given position1017 - Parameters:1018 - `x` (number): X coordinate1019 - `y` (number): Y coordinate1020 - Read-only: **false**10211022<!-- NOTE: This has been generated via update-readme.js -->10231024- **browser_mouse_down**1025 - Title: Press mouse down1026 - Description: Press mouse down1027 - Parameters:1028 - `button` (string, optional): Button to press, defaults to left1029 - Read-only: **false**10301031<!-- NOTE: This has been generated via update-readme.js -->10321033- **browser_mouse_drag_xy**1034 - Title: Drag mouse1035 - Description: Drag left mouse button to a given position1036 - Parameters:1037 - `startX` (number): Start X coordinate1038 - `startY` (number): Start Y coordinate1039 - `endX` (number): End X coordinate1040 - `endY` (number): End Y coordinate1041 - Read-only: **false**10421043<!-- NOTE: This has been generated via update-readme.js -->10441045- **browser_mouse_move_xy**1046 - Title: Move mouse1047 - Description: Move mouse to a given position1048 - Parameters:1049 - `x` (number): X coordinate1050 - `y` (number): Y coordinate1051 - Read-only: **false**10521053<!-- NOTE: This has been generated via update-readme.js -->10541055- **browser_mouse_up**1056 - Title: Press mouse up1057 - Description: Press mouse up1058 - Parameters:1059 - `button` (string, optional): Button to press, defaults to left1060 - Read-only: **false**10611062<!-- NOTE: This has been generated via update-readme.js -->10631064- **browser_mouse_wheel**1065 - Title: Scroll mouse wheel1066 - Description: Scroll mouse wheel1067 - Parameters:1068 - `deltaX` (number): X delta1069 - `deltaY` (number): Y delta1070 - Read-only: **false**10711072</details>10731074<details>1075<summary><b>PDF generation (opt-in via --caps=pdf)</b></summary>10761077<!-- NOTE: This has been generated via update-readme.js -->10781079- **browser_pdf_save**1080 - Title: Save as PDF1081 - Description: Save page as PDF1082 - Parameters:1083 - `filename` (string, optional): File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified. Prefer relative file names to stay within the output directory.1084 - Read-only: **true**10851086</details>10871088<details>1089<summary><b>Test assertions (opt-in via --caps=testing)</b></summary>10901091<!-- NOTE: This has been generated via update-readme.js -->10921093- **browser_generate_locator**1094 - Title: Create locator for element1095 - Description: Generate locator for the given element to use in tests1096 - Parameters:1097 - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element1098 - `ref` (string): Exact target element reference from the page snapshot1099 - Read-only: **true**11001101<!-- NOTE: This has been generated via update-readme.js -->11021103- **browser_verify_element_visible**1104 - Title: Verify element visible1105 - Description: Verify element is visible on the page1106 - Parameters:1107 - `role` (string): ROLE of the element. Can be found in the snapshot like this: `- {ROLE} "Accessible Name":`1108 - `accessibleName` (string): ACCESSIBLE_NAME of the element. Can be found in the snapshot like this: `- role "{ACCESSIBLE_NAME}"`1109 - Read-only: **false**11101111<!-- NOTE: This has been generated via update-readme.js -->11121113- **browser_verify_list_visible**1114 - Title: Verify list visible1115 - Description: Verify list is visible on the page1116 - Parameters:1117 - `element` (string): Human-readable list description1118 - `ref` (string): Exact target element reference that points to the list1119 - `items` (array): Items to verify1120 - Read-only: **false**11211122<!-- NOTE: This has been generated via update-readme.js -->11231124- **browser_verify_text_visible**1125 - Title: Verify text visible1126 - Description: Verify text is visible on the page. Prefer browser_verify_element_visible if possible.1127 - Parameters:1128 - `text` (string): TEXT to verify. Can be found in the snapshot like this: `- role "Accessible Name": {TEXT}` or like this: `- text: {TEXT}`1129 - Read-only: **false**11301131<!-- NOTE: This has been generated via update-readme.js -->11321133- **browser_verify_value**1134 - Title: Verify value1135 - Description: Verify element value1136 - Parameters:1137 - `type` (string): Type of the element1138 - `element` (string): Human-readable element description1139 - `ref` (string): Exact target element reference that points to the element1140 - `value` (string): Value to verify. For checkbox, use "true" or "false".1141 - Read-only: **false**11421143</details>11441145<details>1146<summary><b>Tracing (opt-in via --caps=tracing)</b></summary>11471148</details>114911501151<!--- End of tools generated section -->1152
Full transparency — inspect the skill content before installing.