Configuration Schema

Complete reference for the Playwright MCP Config type

The Config type defines all configuration options for customizing the Playwright MCP server behavior. All fields are optional.

Browser Configuration

browser · object

Browser-related configuration options.

Show properties

browserName · 'chromium' | 'firefox' | 'webkit'

The type of browser to use. Defaults to 'chromium'.

isolated · boolean

Keep the browser profile in memory, do not save it to disk. When enabled, each session starts fresh.

userDataDir · string

Path to a user data directory for browser profile persistence. Temporary directory is created by default.

launchOptions · playwright.LaunchOptions

Launch options passed to Playwright’s launchPersistentContext. See Playwright LaunchOptions.

Useful for settings like channel, headless, executablePath, etc.

contextOptions · playwright.BrowserContextOptions

Context options for the browser context. Useful for settings like viewport, userAgent, locale, etc.

cdpEndpoint · string

Chrome DevTools Protocol endpoint to connect to an existing browser instance (Chromium family browsers only).

cdpHeaders · Record<string, string>

CDP headers to send with the connect request.

cdpTimeout · number

Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

remoteEndpoint · string

Remote endpoint to connect to an existing Playwright server.

initPage · string[]

Paths to TypeScript files to add as initialization scripts for Playwright page object. These scripts run with access to the page object.

initScript · 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.

Extension Mode

extension · boolean

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.

Server Configuration

server · object

HTTP server configuration for SSE or MCP transport.

Show properties

port · number

The port to listen on for SSE or MCP transport.

host · string

The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.

allowedHosts · 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 DNS rebinding protection.

Capabilities

capabilities · ToolCapability[]

List of enabled tool capabilities. See Tool Capabilities for details.

Possible values:

• 'config' - Configuration tools
• 'core' - Core browser automation features
• 'core-navigation' - Navigation tools
• 'core-tabs' - Tab management
• 'core-input' - Input and interaction tools
• 'core-install' - Browser installation
• 'network' - Network request inspection
• 'pdf' - PDF generation
• 'storage' - Storage management
• 'testing' - Test assertions and verification
• 'vision' - Coordinate-based interactions
• 'devtools' - Developer tools features

Session Recording

saveSession · boolean

Whether to save the Playwright session into the output directory.

saveTrace · boolean

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

saveVideo · object

If specified, saves the Playwright video of the session into the output directory.

Show properties

width · number · required

Video width in pixels.

height · number · required

Video height in pixels.

Browser Context Sharing

sharedBrowserContext · boolean

Reuse the same browser context between all connected HTTP clients.

Secrets Management

secrets · Record<string, string>

Secrets are used to prevent LLM from getting sensitive data while automating scenarios such as authentication.

Note: Prefer browser.contextOptions.storageState over secrets file as a more secure alternative.

Output Configuration

outputDir · string

The directory to save output files (screenshots, PDFs, traces, etc.).

outputMode · 'file' | 'stdout'

Whether to save snapshots, console messages, network logs and other session logs to a file or to the standard output. Defaults to 'stdout'.

Console Messages

console · object

Console message configuration.

Show properties

level · 'error' | 'warning' | 'info' | 'debug'

The level of console messages to return. Each level includes the messages of more severe levels. Defaults to 'info'.

Network Configuration

network · object

Network request filtering configuration.

Show properties

allowedOrigins · string[]

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

blockedOrigins · string[]

List of origins to block the browser from requesting. 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

Test ID Attribute

testIdAttribute · string

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

Timeouts

timeouts · object

Timeout configuration for actions and navigation.

Show properties

action · number

Configures default action timeout. See Playwright page.setDefaultTimeout. Defaults to 5000ms.

navigation · number

Configures default navigation timeout. See Playwright page.setDefaultNavigationTimeout. Defaults to 60000ms.

Image Responses

imageResponses · 'allow' | 'omit'

Whether to send image responses to the client. Defaults to 'allow'.

Snapshot Configuration

snapshot · object

Page snapshot configuration.

Show properties

mode · 'incremental' | 'full' | 'none'

When taking snapshots for responses, specifies the mode to use. Defaults to 'incremental'.

File Access

allowUnrestrictedFileAccess · boolean

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.

Code Generation

codegen · 'typescript' | 'none'

Specify the language to use for code generation. Defaults to 'typescript'.

Complete Example

import { createConnection } from '@playwright/mcp';

const server = await createConnection({
  browser: {
    browserName: 'chromium',
    isolated: false,
    userDataDir: './browser-profile',
    launchOptions: {
      headless: true,
      args: ['--no-sandbox']
    },
    contextOptions: {
      viewport: { width: 1920, height: 1080 },
      userAgent: 'Custom MCP Agent'
    }
  },
  server: {
    port: 8931,
    host: '0.0.0.0'
  },
  capabilities: ['core', 'pdf', 'vision', 'testing'],
  saveTrace: true,
  saveVideo: {
    width: 1280,
    height: 720
  },
  outputDir: './output',
  outputMode: 'file',
  console: {
    level: 'info'
  },
  network: {
    blockedOrigins: ['https://ads.example.com:*']
  },
  timeouts: {
    action: 10000,
    navigation: 30000
  },
  imageResponses: 'allow',
  snapshot: {
    mode: 'incremental'
  },
  codegen: 'typescript'
});

Related

• createConnection - Main API function
• Tool Capabilities - Capability groups reference