> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/playwright-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure Playwright MCP server with command-line arguments, environment variables, or a JSON configuration file

Playwright MCP server can be configured using command-line arguments, environment variables, or a JSON configuration file.

## Command-Line Arguments

All configuration options can be provided as command-line arguments in the `args` array of your MCP server configuration:

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--browser",
        "chromium"
      ]
    }
  }
}
```

## Environment Variables

Every command-line option has a corresponding environment variable with the `PLAYWRIGHT_MCP_` prefix:

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "PLAYWRIGHT_MCP_HEADLESS": "true",
        "PLAYWRIGHT_MCP_BROWSER": "chromium"
      }
    }
  }
}
```

## Configuration File

You can use a JSON configuration file for more complex setups. Specify the file path using the `--config` option:

```json theme={null}
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--config",
        "path/to/config.json"
      ]
    }
  }
}
```

### Configuration File Schema

```typescript theme={null}
{
  /**
   * The browser to use.
   */
  browser?: {
    /**
     * The type of browser to use.
     */
    browserName?: 'chromium' | 'firefox' | 'webkit';

    /**
     * Keep the browser profile in memory, do not save it to disk.
     */
    isolated?: boolean;

    /**
     * Path to a user data directory for browser profile persistence.
     * Temporary directory is created by default.
     */
    userDataDir?: string;

    /**
     * Launch options passed to
     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
     *
     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
     */
    launchOptions?: playwright.LaunchOptions;

    /**
     * Context options for the browser context.
     *
     * This is useful for settings options like `viewport`.
     */
    contextOptions?: playwright.BrowserContextOptions;

    /**
     * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
     */
    cdpEndpoint?: string;

    /**
     * CDP headers to send with the connect request.
     */
    cdpHeaders?: Record<string, string>;

    /**
     * Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
     */
    cdpTimeout?: number;

    /**
     * Remote endpoint to connect to an existing Playwright server.
     */
    remoteEndpoint?: string;

    /**
     * Paths to TypeScript files to add as initialization scripts for Playwright page.
     */
    initPage?: string[];

    /**
     * Paths to JavaScript files to add as initialization scripts.
     * The scripts will be evaluated in every page before any of the page's scripts.
     */
    initScript?: string[];
  },

  /**
   * Connect to a running browser instance (Edge/Chrome only). If specified, `browser`
   * config is ignored.
   * Requires the "Playwright MCP Bridge" browser extension to be installed.
   */
  extension?: boolean;

  server?: {
    /**
     * The port to listen on for SSE or MCP transport.
     */
    port?: number;

    /**
     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
     */
    host?: string;

    /**
     * The hosts this server is allowed to serve from. Defaults to the host server is bound to.
     * This is not for CORS, but rather for the DNS rebinding protection.
     */
    allowedHosts?: string[];
  },

  /**
   * List of enabled tool capabilities. Possible values:
   *   - 'core': Core browser automation features.
   *   - 'pdf': PDF generation and manipulation.
   *   - 'vision': Coordinate-based interactions.
   *   - 'devtools': Developer tools features.
   */
  capabilities?: ToolCapability[];

  /**
   * Whether to save the Playwright session into the output directory.
   */
  saveSession?: boolean;

  /**
   * Whether to save the Playwright trace of the session into the output directory.
   */
  saveTrace?: boolean;

  /**
   * If specified, saves the Playwright video of the session into the output directory.
   */
  saveVideo?: {
    width: number;
    height: number;
  };

  /**
   * Reuse the same browser context between all connected HTTP clients.
   */
  sharedBrowserContext?: 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.
   */
  outputDir?: string;

  /**
   * Whether to save snapshots, console messages, network logs and other session logs to a file or to the standard output. Defaults to "stdout".
   */
  outputMode?: 'file' | 'stdout';

  console?: {
    /**
     * The level of console messages to return. Each level includes the messages of more severe levels. Defaults to "info".
     */
    level?: 'error' | 'warning' | 'info' | 'debug';
  },

  network?: {
    /**
     * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
     *
     * Supported formats:
     * - Full origin: `https://example.com:8080` - matches only that origin
     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
     */
    allowedOrigins?: string[];

    /**
     * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
     *
     * Supported formats:
     * - Full origin: `https://example.com:8080` - matches only that origin
     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
     */
    blockedOrigins?: string[];
  };

  /**
   * Specify the attribute to use for test ids, defaults to "data-testid".
   */
  testIdAttribute?: 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.
   */
  imageResponses?: 'allow' | 'omit';

  snapshot?: {
    /**
     * When taking snapshots for responses, specifies the mode to use.
     */
    mode?: 'incremental' | 'full' | 'none';
  };

  /**
   * Whether to allow file uploads from anywhere on the file system.
   * By default (false), file uploads are restricted to paths within the MCP roots only.
   */
  allowUnrestrictedFileAccess?: boolean;

  /**
   * Specify the language to use for code generation.
   */
  codegen?: 'typescript' | 'none';
}
```

## Available Options

<ParamField path="--allowed-hosts" type="string">
  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.

  **Environment variable:** `PLAYWRIGHT_MCP_ALLOWED_HOSTS`
</ParamField>

<ParamField path="--allowed-origins" type="string">
  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.

  **Environment variable:** `PLAYWRIGHT_MCP_ALLOWED_ORIGINS`
</ParamField>

<ParamField path="--allow-unrestricted-file-access" type="boolean">
  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.

  **Environment variable:** `PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS`
</ParamField>

<ParamField path="--blocked-origins" type="string">
  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.

  **Environment variable:** `PLAYWRIGHT_MCP_BLOCKED_ORIGINS`
</ParamField>

<ParamField path="--block-service-workers" type="boolean">
  Block service workers.

  **Environment variable:** `PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS`
</ParamField>

<ParamField path="--browser" type="string">
  Browser or chrome channel to use. Possible values: `chrome`, `firefox`, `webkit`, `msedge`.

  **Environment variable:** `PLAYWRIGHT_MCP_BROWSER`
</ParamField>

<ParamField path="--caps" type="string">
  Comma-separated list of additional capabilities to enable. Possible values: `vision`, `pdf`, `devtools`.

  **Environment variable:** `PLAYWRIGHT_MCP_CAPS`
</ParamField>

<ParamField path="--cdp-endpoint" type="string">
  CDP endpoint to connect to.

  **Environment variable:** `PLAYWRIGHT_MCP_CDP_ENDPOINT`
</ParamField>

<ParamField path="--cdp-header" type="string">
  CDP headers to send with the connect request. Multiple can be specified.

  **Environment variable:** `PLAYWRIGHT_MCP_CDP_HEADER`
</ParamField>

<ParamField path="--cdp-timeout" type="number">
  Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000ms.

  **Environment variable:** `PLAYWRIGHT_MCP_CDP_TIMEOUT`
</ParamField>

<ParamField path="--codegen" type="string">
  Specify the language to use for code generation. Possible values: `typescript`, `none`. Default is `typescript`.

  **Environment variable:** `PLAYWRIGHT_MCP_CODEGEN`
</ParamField>

<ParamField path="--config" type="string">
  Path to the configuration file.

  **Environment variable:** `PLAYWRIGHT_MCP_CONFIG`
</ParamField>

<ParamField path="--console-level" type="string">
  Level of console messages to return: `error`, `warning`, `info`, `debug`. Each level includes the messages of more severe levels.

  **Environment variable:** `PLAYWRIGHT_MCP_CONSOLE_LEVEL`
</ParamField>

<ParamField path="--device" type="string">
  Device to emulate, for example: "iPhone 15".

  **Environment variable:** `PLAYWRIGHT_MCP_DEVICE`
</ParamField>

<ParamField path="--executable-path" type="string">
  Path to the browser executable.

  **Environment variable:** `PLAYWRIGHT_MCP_EXECUTABLE_PATH`
</ParamField>

<ParamField path="--extension" type="boolean">
  Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.

  **Environment variable:** `PLAYWRIGHT_MCP_EXTENSION`
</ParamField>

<ParamField path="--grant-permissions" type="string">
  List of permissions to grant to the browser context, for example `geolocation`, `clipboard-read`, `clipboard-write`.

  **Environment variable:** `PLAYWRIGHT_MCP_GRANT_PERMISSIONS`
</ParamField>

<ParamField path="--headless" type="boolean">
  Run browser in headless mode. Headed by default.

  **Environment variable:** `PLAYWRIGHT_MCP_HEADLESS`
</ParamField>

<ParamField path="--host" type="string">
  Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.

  **Environment variable:** `PLAYWRIGHT_MCP_HOST`
</ParamField>

<ParamField path="--ignore-https-errors" type="boolean">
  Ignore HTTPS errors.

  **Environment variable:** `PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS`
</ParamField>

<ParamField path="--init-page" type="string">
  Path to TypeScript file to evaluate on Playwright page object.

  **Environment variable:** `PLAYWRIGHT_MCP_INIT_PAGE`
</ParamField>

<ParamField path="--init-script" type="string">
  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.

  **Environment variable:** `PLAYWRIGHT_MCP_INIT_SCRIPT`
</ParamField>

<ParamField path="--isolated" type="boolean">
  Keep the browser profile in memory, do not save it to disk.

  **Environment variable:** `PLAYWRIGHT_MCP_ISOLATED`
</ParamField>

<ParamField path="--image-responses" type="string">
  Whether to send image responses to the client. Can be `allow` or `omit`. Defaults to `allow`.

  **Environment variable:** `PLAYWRIGHT_MCP_IMAGE_RESPONSES`
</ParamField>

<ParamField path="--no-sandbox" type="boolean">
  Disable the sandbox for all process types that are normally sandboxed.

  **Environment variable:** `PLAYWRIGHT_MCP_NO_SANDBOX`
</ParamField>

<ParamField path="--output-dir" type="string">
  Path to the directory for output files.

  **Environment variable:** `PLAYWRIGHT_MCP_OUTPUT_DIR`
</ParamField>

<ParamField path="--output-mode" type="string">
  Whether to save snapshots, console messages, network logs to a file or to the standard output. Can be `file` or `stdout`. Default is `stdout`.

  **Environment variable:** `PLAYWRIGHT_MCP_OUTPUT_MODE`
</ParamField>

<ParamField path="--port" type="number">
  Port to listen on for SSE transport.

  **Environment variable:** `PLAYWRIGHT_MCP_PORT`
</ParamField>

<ParamField path="--proxy-bypass" type="string">
  Comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com".

  **Environment variable:** `PLAYWRIGHT_MCP_PROXY_BYPASS`
</ParamField>

<ParamField path="--proxy-server" type="string">
  Specify proxy server, for example "[http://myproxy:3128](http://myproxy:3128)" or "socks5://myproxy:8080".

  **Environment variable:** `PLAYWRIGHT_MCP_PROXY_SERVER`
</ParamField>

<ParamField path="--sandbox" type="boolean">
  Enable the sandbox for all process types that are normally not sandboxed.

  **Environment variable:** `PLAYWRIGHT_MCP_SANDBOX`
</ParamField>

<ParamField path="--save-session" type="boolean">
  Whether to save the Playwright MCP session into the output directory.

  **Environment variable:** `PLAYWRIGHT_MCP_SAVE_SESSION`
</ParamField>

<ParamField path="--save-trace" type="boolean">
  Whether to save the Playwright Trace of the session into the output directory.

  **Environment variable:** `PLAYWRIGHT_MCP_SAVE_TRACE`
</ParamField>

<ParamField path="--save-video" type="string">
  Whether to save the video of the session into the output directory. For example "--save-video=800x600".

  **Environment variable:** `PLAYWRIGHT_MCP_SAVE_VIDEO`
</ParamField>

<ParamField path="--secrets" type="string">
  Path to a file containing secrets in the dotenv format.

  **Environment variable:** `PLAYWRIGHT_MCP_SECRETS`
</ParamField>

<ParamField path="--shared-browser-context" type="boolean">
  Reuse the same browser context between all connected HTTP clients.

  **Environment variable:** `PLAYWRIGHT_MCP_SHARED_BROWSER_CONTEXT`
</ParamField>

<ParamField path="--snapshot-mode" type="string">
  When taking snapshots for responses, specifies the mode to use. Can be `incremental`, `full`, or `none`. Default is `incremental`.

  **Environment variable:** `PLAYWRIGHT_MCP_SNAPSHOT_MODE`
</ParamField>

<ParamField path="--storage-state" type="string">
  Path to the storage state file for isolated sessions.

  **Environment variable:** `PLAYWRIGHT_MCP_STORAGE_STATE`
</ParamField>

<ParamField path="--test-id-attribute" type="string">
  Specify the attribute to use for test ids. Defaults to "data-testid".

  **Environment variable:** `PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE`
</ParamField>

<ParamField path="--timeout-action" type="number">
  Specify action timeout in milliseconds. Defaults to 5000ms.

  **Environment variable:** `PLAYWRIGHT_MCP_TIMEOUT_ACTION`
</ParamField>

<ParamField path="--timeout-navigation" type="number">
  Specify navigation timeout in milliseconds. Defaults to 60000ms.

  **Environment variable:** `PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION`
</ParamField>

<ParamField path="--user-agent" type="string">
  Specify user agent string.

  **Environment variable:** `PLAYWRIGHT_MCP_USER_AGENT`
</ParamField>

<ParamField path="--user-data-dir" type="string">
  Path to the user data directory. If not specified, a temporary directory will be created.

  **Environment variable:** `PLAYWRIGHT_MCP_USER_DATA_DIR`
</ParamField>

<ParamField path="--viewport-size" type="string">
  Specify browser viewport size in pixels, for example "1280x720".

  **Environment variable:** `PLAYWRIGHT_MCP_VIEWPORT_SIZE`
</ParamField>