@playwright/mcp 0.0.36 → 0.0.37-alpha-2025-09-09

package/README.md

@@ -76,7 +76,7 @@ For more information, see the [Codex MCP documentation](https://github.com/opena
 
 #### Click the button to install:
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](cursor://anysphere.cursor-deeplink/mcp/install?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
 
 #### Or install manually:
 
@@ -180,52 +180,65 @@ Playwright MCP server supports following arguments. They can be provided in the
 
 ```
 > npx @playwright/mcp@latest --help
-  --allowed-origins <origins>  semicolon-separated list of origins to allow the
-                               browser to request. Default is to allow all.
-  --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.
-  --block-service-workers      block service workers
-  --browser <browser>          browser or chrome channel to use, possible
-                               values: chrome, firefox, webkit, msedge.
-  --caps <caps>                comma-separated list of additional capabilities
-                               to enable, possible values: vision, pdf.
-  --cdp-endpoint <endpoint>    CDP endpoint to connect to.
-  --config <path>              path to the configuration file.
-  --device <device>            device to emulate, for example: "iPhone 15"
-  --executable-path <path>     path to the browser executable.
-  --extension                  Connect to a running browser instance
-                               (Edge/Chrome only). Requires the "Playwright MCP
-                               Bridge" browser extension to be installed.
-  --headless                   run browser in headless mode, headed by default
-  --host <host>                host to bind server to. Default is localhost. Use
-                               0.0.0.0 to bind to all interfaces.
-  --ignore-https-errors        ignore https errors
-  --isolated                   keep the browser profile in memory, do not save
-                               it to disk.
-  --image-responses <mode>     whether to send image responses to the client.
-                               Can be "allow" or "omit", Defaults to "allow".
-  --no-sandbox                 disable the sandbox for all process types that
-                               are normally sandboxed.
-  --output-dir <path>          path to the directory for output files.
-  --port <port>                port to listen on for SSE transport.
-  --proxy-bypass <bypass>      comma-separated domains to bypass proxy, for
-                               example ".com,chromium.org,.domain.com"
-  --proxy-server <proxy>       specify proxy server, for example
-                               "http://myproxy:3128" or "socks5://myproxy:8080"
-  --save-session               Whether to save the Playwright MCP session into
-                               the output directory.
-  --save-trace                 Whether to save the Playwright Trace of the
-                               session into the output directory.
-  --storage-state <path>       path to the storage state file for isolated
-                               sessions.
-  --user-agent <ua string>     specify user agent string
-  --user-data-dir <path>       path to the user data directory. If not
-                               specified, a temporary directory will be created.
-  --viewport-size <size>       specify browser viewport size in pixels, for
-                               example "1280, 720"
+  --allowed-origins <origins>     semicolon-separated list of origins to allow
+                                  the browser to request. Default is to allow
+                                  all.
+  --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.
+  --block-service-workers         block service workers
+  --browser <browser>             browser or chrome channel to use, possible
+                                  values: chrome, firefox, webkit, msedge.
+  --caps <caps>                   comma-separated list of additional
+                                  capabilities to enable, possible values:
+                                  vision, pdf.
+  --cdp-endpoint <endpoint>       CDP endpoint to connect to.
+  --cdp-header <headers...>       CDP headers to send with the connect request,
+                                  multiple can be specified.
+  --config <path>                 path to the configuration file.
+  --device <device>               device to emulate, for example: "iPhone 15"
+  --executable-path <path>        path to the browser executable.
+  --extension                     Connect to a running browser instance
+                                  (Edge/Chrome only). Requires the "Playwright
+                                  MCP Bridge" browser extension to be installed.
+  --headless                      run browser in headless mode, headed by
+                                  default
+  --host <host>                   host to bind server to. Default is localhost.
+                                  Use 0.0.0.0 to bind to all interfaces.
+  --ignore-https-errors           ignore https errors
+  --isolated                      keep the browser profile in memory, do not
+                                  save it to disk.
+  --image-responses <mode>        whether to send image responses to the client.
+                                  Can be "allow" or "omit", Defaults to "allow".
+  --no-sandbox                    disable the sandbox for all process types that
+                                  are normally sandboxed.
+  --output-dir <path>             path to the directory for output files.
+  --port <port>                   port to listen on for SSE transport.
+  --proxy-bypass <bypass>         comma-separated domains to bypass proxy, for
+                                  example ".com,chromium.org,.domain.com"
+  --proxy-server <proxy>          specify proxy server, for example
+                                  "http://myproxy:3128" or
+                                  "socks5://myproxy:8080"
+  --save-session                  Whether to save the Playwright MCP session
+                                  into the output directory.
+  --save-trace                    Whether to save the Playwright Trace of the
+                                  session into the output directory.
+  --secrets <path>                path to a file containing secrets in the
+                                  dotenv format
+  --storage-state <path>          path to the storage state file for isolated
+                                  sessions.
+  --timeout-action <timeout>      specify action timeout in milliseconds,
+                                  defaults to 5000ms
+  --timeout-navigation <timeout>  specify navigation timeout in milliseconds,
+                                  defaults to 60000ms
+  --user-agent <ua string>        specify user agent string
+  --user-data-dir <path>          path to the user data directory. If not
+                                  specified, a temporary directory will be
+                                  created.
+  --viewport-size <size>          specify browser viewport size in pixels, for
+                                  example "1280, 720"
 ```
 
 <!--- End of options generated section -->
@@ -442,6 +455,7 @@ http.createServer(async (req, res) => {
     - `ref` (string): Exact target element reference from the page snapshot
     - `doubleClick` (boolean, optional): Whether to perform a double click instead of a single click
     - `button` (string, optional): Button to click, defaults to left
+    - `modifiers` (array, optional): Modifier keys to press
   - Read-only: **false**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -752,5 +766,26 @@ http.createServer(async (req, res) => {
 
 </details>
 
+<details>
+<summary><b>Tracing (opt-in via --caps=tracing)</b></summary>
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_start_tracing**
+  - Title: Start tracing
+  - Description: Start trace recording
+  - Parameters: None
+  - Read-only: **true**
+
+<!-- NOTE: This has been generated via update-readme.js -->
+
+- **browser_stop_tracing**
+  - Title: Stop tracing
+  - Description: Stop trace recording
+  - Parameters: None
+  - Read-only: **true**
+
+</details>
+
 
 <!--- End of tools generated section -->

package/cli.js

@@ -15,4 +15,10 @@
  * limitations under the License.
  */
 
-import './lib/program.js';
+const { program } = require('playwright-core/lib/utilsBundle');
+const { decorateCommand } = require('playwright/lib/mcp/program');
+
+const packageJSON = require('./package.json');
+const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
+decorateCommand(p, packageJSON.version)
+void program.parseAsync(process.argv);

package/config.d.ts

@@ -59,6 +59,11 @@ export type Config = {
      */
     cdpEndpoint?: string;
 
+    /**
+     * CDP headers to send with the connect request.
+     */
+    cdpHeaders?: Record<string, string>;
+
     /**
      * Remote endpoint to connect to an existing Playwright server.
      */
@@ -95,6 +100,13 @@ export type Config = {
    */
   saveTrace?: boolean;
 
+  /**
+   * Secrets are used to prevent LLM from getting sensitive data while
+   * automating scenarios such as authentication.
+   * Prefer the browser.contextOptions.storageState over secrets file as a more secure alternative.
+   */
+  secrets?: Record<string, string>;
+
   /**
    * The directory to save output files.
    */
@@ -112,6 +124,18 @@ export type Config = {
     blockedOrigins?: string[];
   };
 
+  timeouts?: {
+    /*
+     * Configures default action timeout: https://playwright.dev/docs/api/class-page#page-set-default-timeout. Defaults to 5000ms.
+     */
+    action?: number;
+
+    /*
+     * Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.
+     */
+    navigation?: number;
+  };
+
   /**
    * 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.
    */

package/index.d.ts

@@ -16,7 +16,7 @@
  */
 
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { Config } from './config.js';
+import type { Config } from './config';
 import type { BrowserContext } from 'playwright';
 
 export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Server>;

package/index.js

@@ -15,5 +15,5 @@
  * limitations under the License.
  */
 
-import { createConnection } from './lib/index.js';
-export { createConnection };
+const { createConnection } = require('playwright/lib/mcp/index');
+module.exports = { createConnection };

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.36",
+  "version": "0.0.37-alpha-2025-09-09",
   "description": "Playwright Tools for MCP",
-  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/microsoft/playwright-mcp.git"
@@ -16,19 +15,15 @@
   },
   "license": "Apache-2.0",
   "scripts": {
-    "build": "tsc",
-    "lint": "npm run update-readme && npm run check-deps && eslint . && tsc --noEmit",
-    "lint-fix": "eslint . --fix",
-    "check-deps": "node utils/check-deps.js",
-    "update-readme": "node utils/update-readme.js",
-    "watch": "tsc --watch",
+    "lint": "npm run update-readme",
+    "update-readme": "node update-readme.js",
+    "docker-build": "docker build --no-cache -t playwright-mcp-dev:latest .",
     "test": "playwright test",
     "ctest": "playwright test --project=chrome",
     "ftest": "playwright test --project=firefox",
     "wtest": "playwright test --project=webkit",
-    "run-server": "node lib/browserServer.js",
-    "clean": "rm -rf lib",
-    "npm-publish": "npm run clean && npm run build && npm run test && npm publish"
+    "dtest": "MCP_IN_DOCKER=1 playwright test --project=chromium-docker",
+    "npm-publish": "npm run clean && npm run test && npm publish"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -38,37 +33,16 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.16.0",
-    "commander": "^13.1.0",
-    "debug": "^4.4.1",
-    "dotenv": "^17.2.0",
-    "mime": "^4.0.7",
-    "playwright": "1.56.0-alpha-1756505518000",
-    "playwright-core": "1.56.0-alpha-1756505518000",
-    "ws": "^8.18.1",
-    "zod": "^3.24.1",
-    "zod-to-json-schema": "^3.24.4"
-  },
-  "devDependencies": {
-    "@anthropic-ai/sdk": "^0.57.0",
-    "@eslint/eslintrc": "^3.2.0",
-    "@eslint/js": "^9.19.0",
-    "@playwright/test": "1.56.0-alpha-1756505518000",
-    "@stylistic/eslint-plugin": "^3.0.1",
-    "@types/debug": "^4.1.12",
-    "@types/node": "^22.13.10",
-    "@types/ws": "^8.18.1",
-    "@typescript-eslint/eslint-plugin": "^8.26.1",
-    "@typescript-eslint/parser": "^8.26.1",
-    "@typescript-eslint/utils": "^8.26.1",
-    "esbuild": "^0.20.1",
-    "eslint": "^9.19.0",
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-notice": "^1.0.0",
-    "openai": "^5.10.2",
-    "typescript": "^5.8.2"
+    "playwright": "1.56.0-alpha-2025-09-06",
+    "playwright-core": "1.56.0-alpha-2025-09-06"
   },
   "bin": {
     "mcp-server-playwright": "cli.js"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "@playwright/test": "1.56.0-alpha-2025-09-06",
+    "@types/node": "^24.3.0",
+    "zod-to-json-schema": "^3.24.6"
   }
 }

package/lib/browserContextFactory.js

@@ -1,211 +0,0 @@
-/**
- * Copyright (c) Microsoft Corporation.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import fs from 'fs';
-import net from 'net';
-import path from 'path';
-import * as playwright from 'playwright';
-// @ts-ignore
-import { registryDirectory } from 'playwright-core/lib/server/registry/index';
-// @ts-ignore
-import { startTraceViewerServer } from 'playwright-core/lib/server';
-import { logUnhandledError, testDebug } from './utils/log.js';
-import { createHash } from './utils/guid.js';
-import { outputFile } from './config.js';
-export function contextFactory(config) {
-    if (config.browser.remoteEndpoint)
-        return new RemoteContextFactory(config);
-    if (config.browser.cdpEndpoint)
-        return new CdpContextFactory(config);
-    if (config.browser.isolated)
-        return new IsolatedContextFactory(config);
-    return new PersistentContextFactory(config);
-}
-class BaseContextFactory {
-    config;
-    _logName;
-    _browserPromise;
-    constructor(name, config) {
-        this._logName = name;
-        this.config = config;
-    }
-    async _obtainBrowser(clientInfo) {
-        if (this._browserPromise)
-            return this._browserPromise;
-        testDebug(`obtain browser (${this._logName})`);
-        this._browserPromise = this._doObtainBrowser(clientInfo);
-        void this._browserPromise.then(browser => {
-            browser.on('disconnected', () => {
-                this._browserPromise = undefined;
-            });
-        }).catch(() => {
-            this._browserPromise = undefined;
-        });
-        return this._browserPromise;
-    }
-    async _doObtainBrowser(clientInfo) {
-        throw new Error('Not implemented');
-    }
-    async createContext(clientInfo) {
-        testDebug(`create browser context (${this._logName})`);
-        const browser = await this._obtainBrowser(clientInfo);
-        const browserContext = await this._doCreateContext(browser);
-        return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
-    }
-    async _doCreateContext(browser) {
-        throw new Error('Not implemented');
-    }
-    async _closeBrowserContext(browserContext, browser) {
-        testDebug(`close browser context (${this._logName})`);
-        if (browser.contexts().length === 1)
-            this._browserPromise = undefined;
-        await browserContext.close().catch(logUnhandledError);
-        if (browser.contexts().length === 0) {
-            testDebug(`close browser (${this._logName})`);
-            await browser.close().catch(logUnhandledError);
-        }
-    }
-}
-class IsolatedContextFactory extends BaseContextFactory {
-    constructor(config) {
-        super('isolated', config);
-    }
-    async _doObtainBrowser(clientInfo) {
-        await injectCdpPort(this.config.browser);
-        const browserType = playwright[this.config.browser.browserName];
-        return browserType.launch({
-            tracesDir: await startTraceServer(this.config, clientInfo.rootPath),
-            ...this.config.browser.launchOptions,
-            handleSIGINT: false,
-            handleSIGTERM: false,
-        }).catch(error => {
-            if (error.message.includes('Executable doesn\'t exist'))
-                throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
-            throw error;
-        });
-    }
-    async _doCreateContext(browser) {
-        return browser.newContext(this.config.browser.contextOptions);
-    }
-}
-class CdpContextFactory extends BaseContextFactory {
-    constructor(config) {
-        super('cdp', config);
-    }
-    async _doObtainBrowser() {
-        return playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
-    }
-    async _doCreateContext(browser) {
-        return this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
-    }
-}
-class RemoteContextFactory extends BaseContextFactory {
-    constructor(config) {
-        super('remote', config);
-    }
-    async _doObtainBrowser() {
-        const url = new URL(this.config.browser.remoteEndpoint);
-        url.searchParams.set('browser', this.config.browser.browserName);
-        if (this.config.browser.launchOptions)
-            url.searchParams.set('launch-options', JSON.stringify(this.config.browser.launchOptions));
-        return playwright[this.config.browser.browserName].connect(String(url));
-    }
-    async _doCreateContext(browser) {
-        return browser.newContext();
-    }
-}
-class PersistentContextFactory {
-    config;
-    name = 'persistent';
-    description = 'Create a new persistent browser context';
-    _userDataDirs = new Set();
-    constructor(config) {
-        this.config = config;
-    }
-    async createContext(clientInfo) {
-        await injectCdpPort(this.config.browser);
-        testDebug('create browser context (persistent)');
-        const userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(clientInfo.rootPath);
-        const tracesDir = await startTraceServer(this.config, clientInfo.rootPath);
-        this._userDataDirs.add(userDataDir);
-        testDebug('lock user data dir', userDataDir);
-        const browserType = playwright[this.config.browser.browserName];
-        for (let i = 0; i < 5; i++) {
-            try {
-                const browserContext = await browserType.launchPersistentContext(userDataDir, {
-                    tracesDir,
-                    ...this.config.browser.launchOptions,
-                    ...this.config.browser.contextOptions,
-                    handleSIGINT: false,
-                    handleSIGTERM: false,
-                });
-                const close = () => this._closeBrowserContext(browserContext, userDataDir);
-                return { browserContext, close };
-            }
-            catch (error) {
-                if (error.message.includes('Executable doesn\'t exist'))
-                    throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
-                if (error.message.includes('ProcessSingleton') || error.message.includes('Invalid URL')) {
-                    // User data directory is already in use, try again.
-                    await new Promise(resolve => setTimeout(resolve, 1000));
-                    continue;
-                }
-                throw error;
-            }
-        }
-        throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
-    }
-    async _closeBrowserContext(browserContext, userDataDir) {
-        testDebug('close browser context (persistent)');
-        testDebug('release user data dir', userDataDir);
-        await browserContext.close().catch(() => { });
-        this._userDataDirs.delete(userDataDir);
-        testDebug('close browser context complete (persistent)');
-    }
-    async _createUserDataDir(rootPath) {
-        const dir = process.env.PWMCP_PROFILES_DIR_FOR_TEST ?? registryDirectory;
-        const browserToken = this.config.browser.launchOptions?.channel ?? this.config.browser?.browserName;
-        // Hesitant putting hundreds of files into the user's workspace, so using it for hashing instead.
-        const rootPathToken = rootPath ? `-${createHash(rootPath)}` : '';
-        const result = path.join(dir, `mcp-${browserToken}${rootPathToken}`);
-        await fs.promises.mkdir(result, { recursive: true });
-        return result;
-    }
-}
-async function injectCdpPort(browserConfig) {
-    if (browserConfig.browserName === 'chromium')
-        browserConfig.launchOptions.cdpPort = await findFreePort();
-}
-async function findFreePort() {
-    return new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.listen(0, () => {
-            const { port } = server.address();
-            server.close(() => resolve(port));
-        });
-        server.on('error', reject);
-    });
-}
-async function startTraceServer(config, rootPath) {
-    if (!config.saveTrace)
-        return undefined;
-    const tracesDir = await outputFile(config, rootPath, `traces-${Date.now()}`);
-    const server = await startTraceViewerServer();
-    const urlPrefix = server.urlPrefix('human-readable');
-    const url = urlPrefix + '/trace/index.html?trace=' + tracesDir + '/trace.json';
-    // eslint-disable-next-line no-console
-    console.error('\nTrace viewer listening on ' + url);
-    return tracesDir;
-}

package/lib/browserServerBackend.js

@@ -1,77 +0,0 @@
-/**
- * Copyright (c) Microsoft Corporation.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { fileURLToPath } from 'url';
-import { Context } from './context.js';
-import { logUnhandledError } from './utils/log.js';
-import { Response } from './response.js';
-import { SessionLog } from './sessionLog.js';
-import { filteredTools } from './tools.js';
-import { toMcpTool } from './mcp/tool.js';
-export class BrowserServerBackend {
-    _tools;
-    _context;
-    _sessionLog;
-    _config;
-    _browserContextFactory;
-    constructor(config, factory) {
-        this._config = config;
-        this._browserContextFactory = factory;
-        this._tools = filteredTools(config);
-    }
-    async initialize(server, clientVersion, roots) {
-        let rootPath;
-        if (roots.length > 0) {
-            const firstRootUri = roots[0]?.uri;
-            const url = firstRootUri ? new URL(firstRootUri) : undefined;
-            rootPath = url ? fileURLToPath(url) : undefined;
-        }
-        this._sessionLog = this._config.saveSession ? await SessionLog.create(this._config, rootPath) : undefined;
-        this._context = new Context({
-            tools: this._tools,
-            config: this._config,
-            browserContextFactory: this._browserContextFactory,
-            sessionLog: this._sessionLog,
-            clientInfo: { ...clientVersion, rootPath },
-        });
-    }
-    async listTools() {
-        return this._tools.map(tool => toMcpTool(tool.schema));
-    }
-    async callTool(name, rawArguments) {
-        const tool = this._tools.find(tool => tool.schema.name === name);
-        if (!tool)
-            throw new Error(`Tool "${name}" not found`);
-        const parsedArguments = tool.schema.inputSchema.parse(rawArguments || {});
-        const context = this._context;
-        const response = new Response(context, name, parsedArguments);
-        context.setRunningTool(name);
-        try {
-            await tool.handle(context, parsedArguments, response);
-            await response.finish();
-            this._sessionLog?.logResponse(response);
-        }
-        catch (error) {
-            response.addError(String(error));
-        }
-        finally {
-            context.setRunningTool(undefined);
-        }
-        return response.serialize();
-    }
-    serverClosed() {
-        void this._context?.dispose().catch(logUnhandledError);
-    }
-}