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:

{
  "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:

{
  "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:

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

Configuration File Schema

{
  /**
   * 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

--allowed-hosts · 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

--allowed-origins · 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

--allow-unrestricted-file-access · 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

--blocked-origins · 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

--block-service-workers · boolean

Block service workers.

Environment variable: PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS

--browser · string

Browser or chrome channel to use. Possible values: chrome, firefox, webkit, msedge.

Environment variable: PLAYWRIGHT_MCP_BROWSER

--caps · string

Comma-separated list of additional capabilities to enable. Possible values: vision, pdf, devtools.

Environment variable: PLAYWRIGHT_MCP_CAPS

--cdp-endpoint · string

CDP endpoint to connect to.

Environment variable: PLAYWRIGHT_MCP_CDP_ENDPOINT

--cdp-header · string

CDP headers to send with the connect request. Multiple can be specified.

Environment variable: PLAYWRIGHT_MCP_CDP_HEADER

--cdp-timeout · number

Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000ms.

Environment variable: PLAYWRIGHT_MCP_CDP_TIMEOUT

--codegen · string

Specify the language to use for code generation. Possible values: typescript, none. Default is typescript.

Environment variable: PLAYWRIGHT_MCP_CODEGEN

--config · string

Path to the configuration file.

Environment variable: PLAYWRIGHT_MCP_CONFIG

--console-level · 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

--device · string

Device to emulate, for example: “iPhone 15”.

Environment variable: PLAYWRIGHT_MCP_DEVICE

--executable-path · string

Path to the browser executable.

Environment variable: PLAYWRIGHT_MCP_EXECUTABLE_PATH

--extension · 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

--grant-permissions · string

List of permissions to grant to the browser context, for example geolocation, clipboard-read, clipboard-write.

Environment variable: PLAYWRIGHT_MCP_GRANT_PERMISSIONS

--headless · boolean

Run browser in headless mode. Headed by default.

Environment variable: PLAYWRIGHT_MCP_HEADLESS

--host · string

Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.

Environment variable: PLAYWRIGHT_MCP_HOST

--ignore-https-errors · boolean

Ignore HTTPS errors.

Environment variable: PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS

--init-page · string

Path to TypeScript file to evaluate on Playwright page object.

Environment variable: PLAYWRIGHT_MCP_INIT_PAGE

--init-script · 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

--isolated · boolean

Keep the browser profile in memory, do not save it to disk.

Environment variable: PLAYWRIGHT_MCP_ISOLATED

--image-responses · string

Whether to send image responses to the client. Can be allow or omit. Defaults to allow.

Environment variable: PLAYWRIGHT_MCP_IMAGE_RESPONSES

--no-sandbox · boolean

Disable the sandbox for all process types that are normally sandboxed.

Environment variable: PLAYWRIGHT_MCP_NO_SANDBOX

--output-dir · string

Path to the directory for output files.

Environment variable: PLAYWRIGHT_MCP_OUTPUT_DIR

--output-mode · 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

--port · number

Port to listen on for SSE transport.

Environment variable: PLAYWRIGHT_MCP_PORT

--proxy-bypass · string

Comma-separated domains to bypass proxy, for example “.com,chromium.org,.domain.com”.

Environment variable: PLAYWRIGHT_MCP_PROXY_BYPASS

--proxy-server · string

Specify proxy server, for example “http://myproxy:3128” or “socks5://myproxy:8080”.

Environment variable: PLAYWRIGHT_MCP_PROXY_SERVER

--sandbox · boolean

Enable the sandbox for all process types that are normally not sandboxed.

Environment variable: PLAYWRIGHT_MCP_SANDBOX

--save-session · boolean

Whether to save the Playwright MCP session into the output directory.

Environment variable: PLAYWRIGHT_MCP_SAVE_SESSION

--save-trace · boolean

Whether to save the Playwright Trace of the session into the output directory.

Environment variable: PLAYWRIGHT_MCP_SAVE_TRACE

--save-video · string

Whether to save the video of the session into the output directory. For example “—save-video=800x600”.

Environment variable: PLAYWRIGHT_MCP_SAVE_VIDEO

--secrets · string

Path to a file containing secrets in the dotenv format.

Environment variable: PLAYWRIGHT_MCP_SECRETS

--shared-browser-context · boolean

Reuse the same browser context between all connected HTTP clients.

Environment variable: PLAYWRIGHT_MCP_SHARED_BROWSER_CONTEXT

--snapshot-mode · 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

--storage-state · string

Path to the storage state file for isolated sessions.

Environment variable: PLAYWRIGHT_MCP_STORAGE_STATE

--test-id-attribute · string

Specify the attribute to use for test ids. Defaults to “data-testid”.

Environment variable: PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE

--timeout-action · number

Specify action timeout in milliseconds. Defaults to 5000ms.

Environment variable: PLAYWRIGHT_MCP_TIMEOUT_ACTION

--timeout-navigation · number

Specify navigation timeout in milliseconds. Defaults to 60000ms.

Environment variable: PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION

--user-agent · string

Specify user agent string.

Environment variable: PLAYWRIGHT_MCP_USER_AGENT

--user-data-dir · string

Path to the user data directory. If not specified, a temporary directory will be created.

Environment variable: PLAYWRIGHT_MCP_USER_DATA_DIR

--viewport-size · string

Specify browser viewport size in pixels, for example “1280x720”.

Environment variable: PLAYWRIGHT_MCP_VIEWPORT_SIZE