Related Pages

Related topics: Key Concepts, Installation Guide

Introduction to Playwright MCP

Playwright MCP (Model Context Protocol) is a server implementation that exposes Playwright browser automation capabilities through the MCP protocol. It enables AI models and tools to interact with web browsers using a standardized interface.

Overview

Playwright MCP acts as a bridge between AI systems and web browsers, providing a comprehensive set of tools for:

• Browser automation and scraping
• UI testing and verification
• Network request monitoring
• PDF generation
• Vision-based interactions
• Storage state management

Package Information

Sources: package.json:3-15, server.json:1-15

Architecture

The Playwright MCP implementation follows a layered architecture where the MCP server delegates browser operations to Playwright's core automation engine.

graph TD
    A[AI Client / MCP Host] -->|MCP Protocol| B[Playwright MCP Server]
    B -->|STDIO Transport| C[playwright-core]
    C -->|Browser Automation| D[Chromium / Firefox / WebKit]
    C -->|PDF Generation| E[PDF Renderer]
    C -->|Vision API| F[Image Processing]

Sources: index.js:1-25, cli.js:1-35

Source Code Location

[!IMPORTANT]

The core implementation has been migrated to the Playwright monorepo. The source code is now located at:

packages/playwright/src/mcp

This repository (microsoft/playwright-mcp) serves as the npm distribution package and coordination point.

Sources: src/README.md:1-5

Tool Capabilities

Playwright MCP organizes its functionality into capability groups. Each capability can be individually enabled or disabled through configuration.

Sources: config.d.ts:25-40

Configuration Options

The server behavior can be customized through the Config type defined in config.d.ts.

Browser Configuration

browser?: {
  browserName?: 'chromium' | 'firefox' | 'webkit';
  isolated?: boolean;
  userDataDir?: string;
  launchOptions?: object;
}

Sources: config.d.ts:48-75

Network Configuration

network?: {
  allowedOrigins?: string[];
  blockedOrigins?: string[];
}

Supported origin formats:

• Full origin: https://example.com:8080
• Wildcard port: http://localhost:*

Sources: config.d.ts:100-115

Console Configuration

console?: {
  level?: 'error' | 'warning' | 'info' | 'debug';
}

Sources: config.d.ts:95-98

CLI Usage

The Playwright MCP CLI is available via cli.js and supports several commands:

# Run with default settings
node cli.js

# Install browser binaries
node cli.js install-browser

# Show version
node cli.js --version

# Show help
node cli.js --help

The CLI is built on top of playwright-core and leverages its command-line utilities.

Sources: cli.js:1-35

Entry Point

The main entry point exports the createConnection function which establishes the MCP connection:

const { tools } = require('playwright-core/lib/coreBundle');
module.exports = { createConnection: tools.createConnection };

Sources: index.js:1-25

Package Scripts

Sources: package.json:18-35

Testing

Tests are located in the tests directory and organized under tests/mcp. To run the test suite:

# Fast path - Chrome only
npm run ctest

# Full path - All browsers
npm run mcp-test

Test execution uses Playwright itself, applying the same testing patterns documented in the official Playwright testing guide.

Sources: CONTRIBUTING.md:45-60, playwright.config.ts:1-30

Development Workflow

graph LR
    A[Fork Repository] --> B[Clone playwright monorepo]
    B --> C[npm ci && npm run watch]
    C --> D[npx playwright install]
    D --> E[Make Changes]
    E --> F[npm run flint]
    F --> G[Add Tests]
    G --> H[Open PR]

1. Clone: git clone https://github.com/microsoft/playwright
2. Install: npm ci && npx playwright install
3. Develop: Make changes in packages/playwright/src/mcp
4. Lint: npm run flint
5. Test: npm run mcp-ctest (fast) or npm run mcp-test (full)
6. Commit: Follow Semantic Commit Messages format
7. PR: Submit pull request for review

Sources: CONTRIBUTING.md:10-55

Commit Convention

Commits must follow semantic format:

<label>(<scope>): <description>

[optional body]

[optional footer with fixes/references]

Labels:

• fix - Bug fixes
• feat - New features
• docs - Documentation changes
• test - Test-only changes
• devops - CI/build changes
• chore - Maintenance tasks

Branch naming for fixes: fix-<issue-number>

Sources: CONTRIBUTING.md:55-90

Version Management

The roll.js script handles Playwright version updates across the project:

// Key functions in roll.js
updatePlaywrightVersion(version)  // Update package.json
copyConfig()                      // Sync config.d.ts from monorepo

To roll to a new Playwright version:

1. Run npm run roll
2. Create branch: git checkout -b roll-pw-<suffix>
3. Run tests: npm test
4. Commit and open PR

Sources: roll.js:1-50

Summary

Playwright MCP provides a production-ready integration layer that brings Playwright's powerful browser automation capabilities to AI systems via the Model Context Protocol. With support for multiple browsers, comprehensive tool coverage, and enterprise-grade features like isolated browser contexts and network filtering, it serves as a robust foundation for AI-driven web interactions.

The project's move to the main Playwright monorepo ensures tight integration with Playwright's development cycle and guarantees that the MCP tools remain synchronized with the latest browser automation features.

Related Pages

Related topics: Introduction to Playwright MCP, Browser Configuration

Key Concepts

Playwright MCP (Model Context Protocol) is a server implementation that exposes Playwright browser automation capabilities through the MCP protocol. It enables AI assistants and other MCP clients to interact with web pages through a standardized tool interface, supporting automation, testing, and web scraping workflows.

Architecture Overview

The Playwright MCP server acts as a bridge between MCP clients and Playwright's browser automation engine. The core implementation resides in the Playwright monorepo at packages/playwright/src/mcp, while this repository serves as the distribution package and configuration layer.

graph TD
    A[MCP Client<br>e.g., AI Assistant] --> B[Playwright MCP Server]
    B --> C[Playwright Core]
    C --> D[Chromium]
    C --> E[Firefox]
    C --> F[WebKit]
    
    B --> G[Browser Context]
    G --> H[Pages/Tabs]
    H --> I[DOM Elements]
    
    J[Config Options] --> B
    K[Tool Capabilities] --> B

Sources: CONTRIBUTING.md:40-44

Tool Capabilities System

The MCP server organizes its functionality into discrete capabilities that can be enabled or disabled based on use case requirements.

Capability Types

Sources: config.d.ts:45-56

Opt-in Capabilities

Capabilities not listed in the core group require explicit enablement via the --caps configuration option. For example:

--caps=network,storage,testing

Opt-in capabilities are documented with the following pattern in user-facing documentation:

Capability Title (opt-in via --caps=capability-name)

Sources: update-readme.js:120-123

Browser Configuration

Browser Types

Browser Isolation

browser?: {
  browserName?: 'chromium' | 'firefox' | 'webkit';
  isolated?: boolean;      // Keep profile in memory only
  userDataDir?: string;    // Custom profile persistence path
};

• isolated (default: true): Browser profile is kept in memory, not saved to disk
• userDataDir: Path for browser profile persistence across sessions

Sources: config.d.ts:8-17

Network Security

Origin-Based Filtering

When an origin matches both lists, it will be blocked.

Supported formats:

• Full origin: https://example.com:8080 - matches exact origin
• Wildcard port: http://localhost:* - matches any port with specified protocol

Sources: config.d.ts:20-35

Timeouts

Configuration location: timeouts in the Config type.

Sources: config.d.ts:47-62

Session Management

Save Session

The saveSession option controls whether Playwright session data is persisted to the output directory.

Shared Browser Context

When sharedBrowserContext is enabled, the same browser context is reused across all connected HTTP clients, enabling state sharing between requests.

saveSession?: boolean;
sharedBrowserContext?: boolean;

Sources: config.d.ts:65-70

Secrets Management

Secrets provide a mechanism to redact sensitive information from tool responses before sending them to clients.

secrets?: Record<string, string>;

Important: Secrets replacement is a convenience feature, not a security measure. Always examine incoming and outgoing data on the client side.

Sources: config.d.ts:75-80

Console Logging

console?: {
  level?: 'error' | 'warning' | 'info' | 'debug';
}

Sources: config.d.ts:91-96

Image Responses

Controls whether image responses are sent to MCP clients:

imageResponses?: 'allow' | 'omit' | 'auto';

Sources: config.d.ts:64

Output Directory

Files generated during MCP operations (screenshots, downloads, traces) are saved to the configured output directory:

outputDir?: string;

Sources: config.d.ts:83

Test ID Attribute

Specify a custom attribute to use for test identification:

testIdAttribute?: string;  // Default: "data-testid"

Sources: config.d.ts:43

Command-Line Interface

CLI Entry Point

The CLI is implemented in cli.js and supports several commands:

const { tools, libCli } = require('playwright-core/lib/coreBundle');
tools.decorateMCPCommand(p, packageJSON.version);

Available Commands

The CLI can forward install-browser to playwright install for browser installation.

Sources: cli.js:24-30

Configuration Precedence

Environment variables take precedence over default values. The mapping follows this pattern:

Example: --browser-name → PLAYWRIGHT_MCP_BROWSER_NAME

Sources: update-readme.js:86-90

Build and Release Workflow

Version Management

The package version is defined in package.json:

{
  "name": "@playwright/mcp",
  "version": "0.0.75"
}

Rolling Playwright Versions

The roll.js script handles updating Playwright dependencies:

1. Updates playwright, playwright-core, and @playwright/test versions
2. Copies config.d.ts from the Playwright monorepo
3. Regenerates README documentation

npm run roll

Sources: roll.js:1-30

Branch Naming Convention

Sources: CLAUDE.md:5

Testing Infrastructure

Test Configuration

Tests are configured via playwright.config.ts:

projects: [
  { name: 'chrome' },
  ...process.env.MCP_IN_DOCKER ? [{
    name: 'chromium-docker',
    grep: /browser_navigate|browser_click/,
    use: {
      mcpBrowser: 'chromium',
      mcpMode: 'docker' as const
    }
  }] : [],
]

Test Commands

MCP tests are located in tests/mcp directory within the Playwright monorepo.

Sources: playwright.config.ts:22-38 Sources: CONTRIBUTING.md:67-72

Test Requirements

• Tests must be hermetic (self-contained, no external dependencies)
• Must work on all three platforms: macOS, Linux, Windows
• Tests are required for new functionality (exceptions for pure refactoring)

Sources: CONTRIBUTING.md:83-85

Commit Conventions

Semantic Commit Format

label(namespace): title

description

footer

Labels

Example

fix(proxy): handle SOCKS proxy authentication

Fixes: https://github.com/microsoft/playwright/issues/39562

Sources: CONTRIBUTING.md:11-31

Contribution Workflow

graph LR
    A[File Issue] --> B[Get Assignment]
    B --> C[Clone Repository]
    C --> D[Create Branch]
    D --> E[Implement Changes]
    E --> F[Add Tests]
    F --> G[Run Tests]
    G --> H{Linter Pass?}
    H -->|No| I[Fix Issues]
    I --> G
    H -->|Yes| J[Commit Changes]
    J --> K[Open PR]
    K --> L[Code Review]
    L --> M[Merge]

Submission Requirements

• Issue required: Every contribution needs a corresponding GitHub issue
• Prior approval: Unsolicited PRs will be closed
• Human oversight: Low-quality AI contributions without human review will be closed

Sources: CONTRIBUTING.md:41-52

Documentation Generation

The update-readme.js script automatically generates documentation sections:

1. Tools section: Lists all MCP tools grouped by capability
2. Options section: CLI options from --help output
3. Config section: TypeScript Config type definition

Generated sections are delimited by markers:

<!--- Tools generated by update-readme.js -->
...
<!--- End of tools generated section --->

Run npm run lint to regenerate documentation.

Sources: update-readme.js:1-150

Related Pages

Related topics: MCP Client Integration, Docker Deployment

Installation Guide

This guide covers all aspects of installing, configuring, and setting up the Playwright MCP (Model Context Protocol) server for development and production use.

Overview

Playwright MCP is an npm package (@playwright/mcp) that provides browser automation tools via the MCP protocol. It enables AI assistants to interact with web browsers through a standardized interface, supporting capabilities like navigation, clicking, input handling, network interception, and testing assertions.

Sources: package.json:1-15

System Requirements

Runtime Requirements

The package explicitly declares its Node.js engine requirement in package.json:

"engines": {
  "node": ">=18"
}

Sources: package.json:12-14

Browser Dependencies

Playwright MCP requires browser binaries to function. The supported browsers are:

Installation Methods

From npm (Global Installation)

For CLI usage across the system:

npm install -g @playwright/mcp

This makes the playwright command available globally:

playwright --help

Sources: cli.js:23-26

From npm (Project Installation)

For use as a project dependency:

npm install @playwright/mcp

Using npx (No Installation)

For one-time execution without installing globally:

npx @playwright/mcp [options]

CLI Options

The MCP server accepts the following command-line options:

Sources: update-readme.js:89-111

Environment Variable Mapping

Every CLI option can be configured via environment variables by prefixing the option name with PLAYWRIGHT_MCP_ and converting dashes to underscores:

export PLAYWRIGHT_MCP_BROWSER=chromium
export PLAYWRIGHT_MCP_OUTPUT_DIR=/tmp/playwright-output
export PLAYWRIGHT_MCP_SECRETS_FILE=./secrets.json

Configuration File

Config File Format

Create a TypeScript config file (e.g., config.ts) with the following structure:

import type { Config } from '@playwright/mcp';

const config: Config = {
  browser: {
    browserName: 'chromium',
    isolated: true,
  },
  capabilities: ['core', 'network'],
  outputDir: '/tmp/playwright-output',
  timeouts: {
    action: 5000,
    navigation: 60000,
    expect: 5000,
  },
};

export default config;

Configuration Options

#### Browser Configuration

Sources: config.d.ts:18-40

#### Capabilities Configuration

The following tool capabilities are available:

Sources: config.d.ts:48-65

#### Timeout Configuration

Sources: config.d.ts:83-97

#### Network Configuration

Origins can be specified as full URLs (https://example.com:8080) or with wildcard ports (http://localhost:*).

Sources: config.d.ts:99-114

Development Setup

Clone the Repository

[!WARNING]

The core of the Playwright MCP was moved to the Playwright monorepo.

Clone the Playwright repository where Playwright MCP source is now located:

git clone https://github.com/microsoft/playwright
cd playwright

Sources: CONTRIBUTING.md:33-43

Install Dependencies

Install all project dependencies:

npm ci

Install Browser Binaries

Download and install the required browser binaries:

npx playwright install

Or install specific browsers:

npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

Sources: CONTRIBUTING.md:44-50

Development Workflow

#### Watch Mode

For active development with automatic rebuilding:

npm run watch

#### Run Tests

Run all MCP tests in Chromium (fast path):

npm run mcp-ctest

Run all tests in three browsers (slow path):

npm run mcp-test

#### Linting

Check code quality using the linter:

npm run flint

Sources: CONTRIBUTING.md:51-70

Test Directory Structure

Tests for Playwright MCP are located at:

tests/mcp/

To list test files:

ls -la tests/mcp

Sources: CONTRIBUTING.md:59-66

Docker Installation

Build the Docker Image

npm run docker-build

This creates a Docker image named playwright-mcp-dev:latest.

Run the Docker Container

npm run docker-run

This starts an interactive session with port 8080 exposed.

Docker Test Mode

Run tests within Docker using Chromium:

npm run dtest

Sources: package.json:23-30

Testing Your Installation

Verify CLI Access

playwright --version

Expected output:

Version <version-number>

Verify MCP Connection

Test that the MCP server starts correctly:

playwright --help

Run Test Suite

Execute the test suite to verify functionality:

npm test

Only proceed with deployment if all tests pass.

Sources: CLAUDE.md:4-5

Package Scripts Reference

Sources: package.json:18-35

Troubleshooting

Node.js Version Error

If you see an engine version error, ensure you have Node.js 18 or later:

node --version
# Should be >= 18.0.0

Browser Installation Failure

If browser installation fails, try with elevated permissions or check network connectivity:

npx playwright install --with-deps

Test Failures

1. Ensure all dependencies are installed: npm ci
2. Ensure browsers are installed: npx playwright install
3. Verify Node.js version: node --version
4. Clear any cached state and retry

Permission Errors

For global installations, you may need sudo on Unix systems:

sudo npm install -g @playwright/mcp

Or use a Node version manager like nvm to avoid permission issues.

Related Pages

Related topics: Installation Guide, Browser Configuration

MCP Client Integration

Overview

MCP Client Integration refers to the mechanism by which the Playwright MCP (Model Context Protocol) server exposes browser automation capabilities as tools that can be consumed by LLM clients. The integration provides a bridge between the MCP protocol and Playwright's browser automation APIs, enabling AI agents to control browsers through a standardized interface.

The MCP server implementation has been moved to the Playwright monorepo, while this repository (microsoft/playwright-mcp) serves as a distribution package and coordination point for the MCP tooling.

Sources: src/README.md

Architecture

System Components

The MCP Client Integration consists of several interconnected components:

graph TD
    A["MCP Client<br/>(LLM Agent)"] --> B["Playwright MCP Server"]
    B --> C["playwright-core<br/>coreBundle"]
    B --> D["playwright-core<br/>tools Bundle"]
    C --> E["Browser Process"]
    D --> E
    E --> F["Page/Document"]
    
    G["CLI Entry Point<br/>(cli.js)"] --> B
    H["Configuration<br/>(config.d.ts)"] --> B
    I["server.json<br/>(Transport Config)"] --> B

Transport Layer

The MCP server uses STDIO transport by default, as specified in the server manifest:

{
  "transport": {
    "type": "stdio"
  }
}

Sources: server.json:13

Configuration Reference

Config Type Definition

The Config type in config.d.ts defines all available configuration options for the MCP server:

export type ToolCapability =
  | 'config'
  | 'core'
  | 'core-navigation'
  | 'core-tabs'
  | 'core-input'
  | 'core-install'
  | 'network'
  | 'pdf'
  | 'storage'
  | 'testing'
  | 'vision'
  | 'devtools';

Sources: config.d.ts:20-30

Configuration Options Table

Sources: config.d.ts:31-150

Secrets Management

The configuration supports secrets replacement for sensitive data:

secrets?: Record<string, string>;

Secrets are used to replace matching plain text in tool responses to prevent LLMs from accidentally receiving sensitive information. This is a convenience feature, not a security mechanism.

Sources: config.d.ts:145-150

Capabilities System

Capability Types

Capabilities control which tool categories are exposed to the MCP client:

Sources: config.d.ts:20-29

Capability Enablement

Capabilities are specified in the capabilities array:

capabilities?: ToolCapability[];

Only listed capabilities will be enabled. If not specified, all capabilities may be available.

Tool Schema and Generation

Tool Information Extraction

The update-readme.js script parses compiled modules to extract tool information for documentation:

async function updateTools(content) {
  console.log('Loading tool information from compiled modules...');
  const generatedLines = /** @type {string[]} */ ([]);
  for (const [capability, tools] of Object.entries(toolsByCapability)) {
    generatedLines.push(``);
  }
  // ...
}

Sources: update-readme.js:95-108

Tool Schema Structure

Each tool follows a standardized schema format:

function formatToolForReadme(tool) {
  const lines = /** @type {string[]} */ ([]);
  lines.push(`- **${tool.name}**`);
  lines.push(`  - Title: ${tool.title}`);
  lines.push(`  - Description: ${tool.description}`);
  
  const inputSchema = tool.inputSchema ? tool.inputSchema.toJSONSchema() : {};
  if (inputSchema.properties) {
    lines.push(`  - Parameters:`);
    Object.entries(inputSchema.properties).forEach(([name, param]) => {
      lines.push(`    - \`${name}\`: ${param.description}`);
    });
  }
  lines.push(`  - Read-only: **${tool.type === 'readOnly'}**`);
  return lines;
}

Sources: update-readme.js:145-167

Config Schema Documentation

The config schema is extracted from config.d.ts and embedded into README:

async function updateConfig(content) {
  const configPath = path.join(__dirname, 'config.d.ts');
  const configContent = await fs.promises.readFile(configPath, 'utf-8');
  const configTypeMatch = configContent.match(/export type Config = (\{[\s\S]*?\n\});/);
  // ...
}

Sources: update-readme.js:115-126

CLI Interface

Command-Line Entry Point

The CLI is implemented in cli.js and provides the primary interface for running the MCP server:

const { program } = require('playwright-core/lib/utilsBundle');
const { tools, libCli } = require('playwright-core/lib/coreBundle');

const packageJSON = require('./package.json');
const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
tools.decorateMCPCommand(p, packageJSON.version);

void program.parseAsync(process.argv);

Sources: cli.js:24-33

CLI Commands

The CLI leverages Playwright's built-in command decoration system from playwright-core:

tools.decorateMCPCommand(p, packageJSON.version);

Sources: cli.js:29

CLI Options Generation

Options are dynamically generated from the CLI help output:

async function updateOptions(content) {
  execSync('node cli.js --help > help.txt');
  const lines = output.toString().split('\n');
  // Parse option lines starting with '  --'
  for (let line of lines) {
    if (line.startsWith('  --')) {
      const l = line.substring('  --'.length);
      const gapIndex = l.indexOf('  ');
      const name = l.substring(0, gapIndex).trim();
      const value = l.substring(gapIndex).trim();
      options.push({ name, value });
    }
  }
}

Sources: update-readme.js:52-65

Testing

Test Configuration

The project uses Playwright's test framework with a dedicated MCP test configuration:

import { defineConfig } from '@playwright/test';

export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  reporter: 'list',
  projects: [
    { name: 'chrome' },
  ],
});

Sources: playwright.config.ts:17-30

Test Commands

Sources: package.json:15-22

Test Requirements

Tests must be:

• Hermetic: No external service dependencies
• Cross-platform: Work on macOS, Linux, and Windows
• Covered by tests: New functionality requires corresponding tests

Sources: CONTRIBUTING.md

Workflow: README Generation

The README is auto-generated from multiple sources:

graph LR
    A["config.d.ts"] --> D["updateReadme()"]
    B["CLI --help"] --> D
    C["Tool Schemas"] --> D
    D --> E["README.md"]

Generation Pipeline

async function updateReadme() {
  const readmePath = path.join(__dirname, 'README.md');
  const readmeContent = await fs.promises.readFile(readmePath, 'utf-8');
  const withTools = await updateTools(readmeContent);
  const withOptions = await updateOptions(withTools);
  const withConfig = await updateConfig(withOptions);
  await fs.promises.writeFile(readmePath, withConfig, 'utf-8');
}

Sources: update-readme.js:130-139

Development Workflow

Local Development

# Clone the Playwright monorepo (source location)
git clone https://github.com/microsoft/playwright
cd playwright

# Install dependencies and run watch mode
npm ci
npm run watch
npx playwright install

# Navigate to MCP source
cd packages/playwright/src/mcp

Sources: CONTRIBUTING.md

Rolling Playwright Updates

The repository maintains synchronization with the Playwright core:

# Run roll script to update dependencies
npm run roll
# This bumps playwright, playwright-core, @playwright/test
# Refreshes config.d.ts
# Regenerates README

Sources: CLAUDE.md

Linting

Before submitting changes, run the linter:

npm run lint

This executes update-readme.js to validate and regenerate documentation.

Sources: package.json:14

Package Information

NPM Package Details

Sources: package.json:1-12

Related Pages

Related topics: User Profiles and Session Management, Security Settings

Browser Configuration

Overview

Browser Configuration in playwright-mcp defines how the Playwright MCP server manages browser instances for automation tasks. The configuration is defined through the Config type in config.d.ts and controls browser selection, launch behavior, session persistence, and security policies.

Sources: config.d.ts:48-120

graph TD
    A[Browser Configuration] --> B[Browser Selection]
    A --> C[Launch Options]
    A --> D[Session Management]
    A --> E[Network Security]
    A --> F[Server Binding]
    
    B --> B1[chromium]
    B --> B2[firefox]
    B --> B3[webkit]
    
    C --> C1[User Data Dir]
    C --> C2[Init Scripts]
    C --> C3[Launch Params]

Browser Type Selection

Supported Browsers

The configuration supports three browser engines:

Sources: config.d.ts:57-64

Configuration Properties

browser?: {
  browserName?: 'chromium' | 'firefox' | 'webkit';
  isolated?: boolean;
  userDataDir?: string;
  launchOptions?: Record<string, any>;
  initPage?: string[];
  initScript?: string[];
}

Sources: config.d.ts:48-87

Profile Management

Isolated Mode

When isolated: true, the browser profile is kept entirely in memory without persisting to disk. This provides:

• Better privacy between sessions
• Clean state for each automation run
• No leftover browser data

Custom User Data Directory

The userDataDir option allows specifying a persistent profile location:

{
  browser: {
    userDataDir: '/path/to/custom/profile'
  }
}

If not specified, the system creates a temporary directory automatically.

Sources: config.d.ts:68-75

Initialization Scripts

Initialization scripts run before any page content, enabling you to inject polyfills, modify prototypes, or set up testing utilities.

TypeScript Scripts (`initPage`)

Paths to TypeScript files that are added as initialization scripts:

{
  browser: {
    initPage: ['./setup.ts', './fixtures.ts']
  }
}

JavaScript Scripts (`initScript`)

Paths to JavaScript files evaluated in every page before page scripts:

{
  browser: {
    initScript: ['./polyfills.js', './mocks.js']
  }
}

Both script types are evaluated in every page created within the browser context.

Sources: config.d.ts:81-87

Extension Support

Playwright MCP can connect to a running browser instance using the Playwright Extension (Chrome/Edge only):

{
  extension: true
}

When extension is enabled:

• The browser configuration is ignored
• Requires the "Playwright Extension" browser add-on to be installed
• Connects to the browser's debugging port

Sources: config.d.ts:89-93

Server Configuration

The server section controls network binding for the MCP transport:

server?: {
  port?: number;
  host?: string;
  allowedHosts?: string[];
}

Sources: config.d.ts:95-107

Capability Management

Capabilities control which tool sets are enabled for the MCP server:

capabilities?: ToolCapability[];

Sources: config.d.ts:33-46

Session Management

Save Session

When enabled, the Playwright session state is persisted to the output directory:

{
  saveSession: true
}

Sources: config.d.ts:115-117

Shared Browser Context

Multiple HTTP clients can share the same browser context:

{
  sharedBrowserContext: true
}

This is useful for environments where multiple requests need to share session state.

Sources: config.d.ts:119-121

Security Configuration

Network Origins

Control which origins the browser can request:

network?: {
  allowedOrigins?: string[];
  blockedOrigins?: string[];
}

Supported formats:

• Full origin: https://example.com:8080 - matches only that exact origin
• Wildcard port: http://localhost:* - matches any port on localhost with http

Origins matching both lists will be blocked.

Sources: config.d.ts:151-165

Secrets Management

Secrets replace matching plain text in tool responses to prevent sensitive data exposure:

{
  secrets: {
    API_KEY: 'sk-xxxxx',
    DB_PASSWORD: 'secret123'
  }
}

Note: This is a convenience feature, not a security measure. Always examine incoming data.

Sources: config.d.ts:123-129

Console Level

Control console message verbosity:

console?: {
  level?: 'error' | 'warning' | 'info' | 'debug';
}

Each level includes messages from more severe levels. Defaults to info.

Sources: config.d.ts:140-146

Timeout Configuration

Configure default timeouts for various operations:

timeouts?: {
  action?: number;      // Default: 5000ms
  navigation?: number; // Default: 60000ms
  expect?: number;     // Default: 5000ms
}

Sources: config.d.ts:131-144

Test Configuration

The test suite uses a dedicated Playwright configuration:

// playwright.config.ts
export default defineConfig<TestOptions>({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  workers: process.env.CI ? 2 : undefined,
  projects: [
    { name: 'chrome' },
    ...process.env.MCP_IN_DOCKER ? [{
      name: 'chromium-docker',
      grep: /browser_navigate|browser_click/,
      use: {
        mcpBrowser: 'chromium',
        mcpMode: 'docker' as const
      }
    }] : [],
  ],
});

The configuration supports:

• Running tests across browser projects
• Docker-based testing environment
• CI-specific constraints (forbidOnly, limited workers)

Sources: playwright.config.ts:1-34

CLI Usage

The CLI provides commands for running and managing the MCP server:

# Run with custom config
npx playwright-mcp --config my-config.json

# Install browser
npx playwright-mcp install-browser

The CLI is decorated using Playwright's core tools and supports the MCP transport protocol.

Sources: cli.js:1-35

Complete Configuration Example

import type { Config } from './config';

const config: Config = {
  browser: {
    browserName: 'chromium',
    isolated: true,
    initScript: ['./setup.js'],
  },
  server: {
    port: 8080,
    host: 'localhost',
  },
  capabilities: ['core', 'network', 'pdf'],
  saveSession: false,
  sharedBrowserContext: true,
  secrets: {
    API_KEY: process.env.API_KEY || '',
  },
  outputDir: './output',
  network: {
    allowedOrigins: ['https://example.com'],
    blockedOrigins: ['https://malicious.com'],
  },
  console: {
    level: 'info',
  },
  timeouts: {
    action: 5000,
    navigation: 30000,
    expect: 3000,
  },
};

Configuration Schema Summary

Related Commands

Sources: package.json:8-27

Related Pages

Related topics: Browser Configuration, Docker Deployment

Security Settings

Playwright MCP provides comprehensive security settings to protect sensitive data, control browser access, and prevent unauthorized network requests. These settings are configurable through the Config type defined in config.d.ts.

Overview

The Playwright MCP server handles browser automation with built-in security mechanisms that address common attack vectors including:

• DNS rebinding attacks
• Unauthorized network access
• Sensitive data exposure
• Session hijacking

All security configurations are optional and have sensible defaults. Administrators should review and configure these settings based on their deployment environment and security requirements.

Configuration Schema

Security settings are defined within the main Config type. The following table summarizes available security-related configuration options:

Network Security

Origin-Based Access Control

Playwright MCP implements origin-based network filtering to control which websites the browser can access.

network?: {
  allowedOrigins?: string[];
  blockedOrigins?: string[];
};

Supported Formats:

Origin Matching Rules:

1. Origins specified in blockedOrigins take precedence over allowedOrigins
2. If an origin matches both lists, it will be blocked
3. If only allowedOrigins is set, only those origins are accessible
4. If only blockedOrigins is set, all origins except blocked are accessible
5. If neither is set, all origins are accessible

Example Configuration:

{
  network: {
    // Allow only specific domains
    allowedOrigins: [
      'https://myapp.example.com',
      'https://api.example.com:8080',
      'http://localhost:*'  // Allow any localhost port for development
    ],
    // Block specific origins
    blockedOrigins: [
      'https://malicious-site.com'
    ]
  }
}

Browser Isolation

Browser isolation ensures that browser profiles and session data are not persisted to disk, reducing the attack surface.

browser?: {
  browserName?: 'chromium' | 'firefox' | 'webkit';
  isolated?: boolean;
  userDataDir?: string;
};

Security Implications:

• isolated: true - Maximum security, no persistent data
• isolated: false - Session persistence, faster subsequent launches

Secrets Management

The secrets configuration provides a convenience mechanism to redact sensitive information from tool responses before they reach the client.

secrets?: Record<string, string>;

How It Works:

1. Define key-value pairs where the key is the pattern to find and value is the replacement
2. All occurrences of the key in tool response text are replaced with the value
3. This is a convenience feature, not a security boundary

Important Security Note:

Secrets are used to replace matching plain text in the tool responses to prevent the LLM from accidentally getting sensitive data. It is a convenience and not a security feature, make sure to always examine information coming in and from the tool on the client.

Sources: config.d.ts

Example Configuration:

{
  secrets: {
    'sk-1234567890abcdef': '[API_KEY_REDACTED]',
    'my-secret-token': '[TOKEN_REDACTED]',
    'password123': '[PASSWORD_REDACTED]'
  }
}

Data Flow Diagram

graph TD
    A[Browser Automation] --> B[Tool Response Generated]
    B --> C{Secrets Configured?}
    C -->|Yes| D[Scan Response for Secret Patterns]
    C -->|No| E[Return Original Response]
    D --> F{Pattern Match Found?}
    F -->|Yes| G[Replace with Redacted Value]
    F -->|No| E
    G --> H[Return Sanitized Response]
    E --> H

Server Security

Host-Based Access Control

The server configuration includes protection against DNS rebinding attacks through the allowedHosts option.

server?: {
  port?: number;
  host?: string;
  allowedHosts?: string[];
};

DNS Rebinding Protection:

The allowedHosts setting protects against DNS rebinding attacks where a malicious domain resolves to your server's IP address. By default, only the host the server is bound to is allowed.

Example Configuration:

{
  server: {
    port: 8080,
    host: '0.0.0.0',  // Bind to all interfaces
    allowedHosts: [
      'localhost',
      '127.0.0.1',
      'my-secure-domain.com'
    ]
  }
}

Console Security

Console message filtering controls what level of browser console output is exposed to clients.

console?: {
  level?: 'error' | 'warning' | 'info' | 'debug';
};

Log Levels:

Security Consideration:

Lower log levels reduce information leakage but may hide important diagnostic information. Choose the appropriate level based on your environment.

Image Response Handling

Control how image responses are handled to prevent potential information disclosure through image metadata.

imageResponses?: 'allow' | 'omit' | 'auto';

Timeouts and Resource Limits

Timeouts help prevent resource exhaustion attacks and ensure predictable behavior.

timeouts?: {
  action?: number;      // Default: 5000ms
  navigation?: number; // Default: 60000ms
  expect?: number;     // Default: 5000ms
};

Security Benefits:

• Prevents hanging operations from consuming resources
• Limits exposure time for potentially malicious pages
• Enables faster failure detection

Security Architecture

graph TD
    subgraph "Client Layer"
        A[MCP Client]
    end
    
    subgraph "Security Middleware"
        B[Host Validation]
        C[Origin Filtering]
        D[Secrets Replacement]
    end
    
    subgraph "Browser Layer"
        E[Playwright Browser]
        F[Isolated Context]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    
    style A fill:#f9f,stroke:#333
    style B fill:#ff9,stroke:#333
    style C fill:#ff9,stroke:#333
    style D fill:#ff9,stroke:#333

Security Best Practices

Production Deployment

``typescript { browser: { isolated: true } } ``

1. Enable Browser Isolation

``typescript { network: { allowedOrigins: ['https://your-domain.com'] } } ``

1. Configure Origin Restrictions

``typescript { console: { level: 'warning' } } // Production ``

1. Use Appropriate Console Level

``typescript { server: { allowedHosts: ['your-domain.com'] } } ``

1. Set Server Host Restrictions

``typescript { timeouts: { action: 5000, navigation: 30000 } } ``

1. Configure Reasonable Timeouts

Development Considerations

• Use console.level: 'debug' only in development
• Consider imageResponses: 'auto' for performance
• Use isolated: false for faster iteration

Reporting Security Issues

Microsoft maintains a security response process for reporting vulnerabilities.

Please do not report security vulnerabilities through public GitHub issues.

Instead, report them to the Microsoft Security Response Center (MSRC):

• Online: https://msrc.microsoft.com/create-report
• Email: [email protected] (PGP encryption available)

Response timeline: You should receive a response within 24 hours. Sources: SECURITY.md

Complete Security Configuration Example

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

const connection = createConnection({
  browser: {
    browserName: 'chromium',
    isolated: true  // Maximum security
  },
  
  network: {
    allowedOrigins: [
      'https://trusted-app.example.com',
      'http://localhost:*'  // Development only
    ],
    blockedOrigins: [
      'https://untrusted-source.com'
    ]
  },
  
  secrets: {
    'sk-api-key': '[REDACTED]',
    'password': '[REDACTED]'
  },
  
  server: {
    port: 8080,
    host: '127.0.0.1',
    allowedHosts: ['localhost', '127.0.0.1']
  },
  
  console: {
    level: 'warning'  // Only errors and warnings
  },
  
  imageResponses: 'auto',
  
  timeouts: {
    action: 5000,
    navigation: 30000,
    expect: 3000
  }
});

Related Documentation

• Playwright MCP README - Main project documentation
• Config Type Definition - Complete configuration types
• Playwright Documentation - Browser automation reference

Related Pages

Related topics: Programmatic Usage, Installation Guide

Docker Deployment

This page documents the Docker deployment capabilities for Playwright MCP, including container-based development, testing, and runtime configuration.

Overview

Playwright MCP supports Docker-based deployment to provide isolated, consistent browser automation environments. The Docker integration enables:

• Containerized browser testing
• Isolated development environments
• Consistent CI/CD pipelines
• Cross-platform browser automation

Docker support is configured through npm scripts defined in package.json and dedicated test configurations in playwright.config.ts.

Docker Scripts

The project provides three npm scripts for managing Docker containers:

Building the Docker Image

npm run docker-build

This creates an image tagged as playwright-mcp-dev:latest. The --no-cache flag ensures a fresh build.

Running the Container

npm run docker-run

The container maps port 8080 for external access and runs in interactive mode (-it).

Cleaning Up

npm run docker-rm

Removes the container to allow fresh deployments.

Sources: package.json:17-19

Docker Test Configuration

Playwright MCP includes dedicated configuration for running tests within Docker containers using Chromium.

Chromium Docker Project

{
  name: 'chromium-docker',
  grep: /browser_navigate|browser_click/,
  use: {
    mcpBrowser: 'chromium',
    mcpMode: 'docker' as const
  }
}

Running Docker Tests

MCP_IN_DOCKER=1 playwright test --project=chromium-docker

The MCP_IN_DOCKER environment variable enables Docker-specific test behavior.

Sources: playwright.config.ts:27-34 Sources: CONTRIBUTING.md:58-60

Browser Configuration for Docker

The config.d.ts file defines browser options that can be configured for Docker deployments.

Browser Configuration Schema

browser?: {
  browserName?: 'chromium' | 'firefox' | 'webkit';
  isolated?: boolean;
  userDataDir?: string;
  launchOptions?: Record<string, unknown>;
};

Docker-Specific Browser Settings

For containerized environments, consider these recommended configurations:

Sources: config.d.ts:28-45

Network Configuration for Containers

Playwright MCP supports fine-grained network control for browser instances within Docker:

Allowed and Blocked Origins

network?: {
  allowedOrigins?: string[];
  blockedOrigins?: string[];
};

Origin Format Examples

Note: Origins matching both allowedOrigins and blockedOrigins will be blocked.

Sources: config.d.ts:70-85

Server Configuration for Docker

The server can be configured to run within Docker containers:

server?: {
  port?: number;
  host?: string;
  allowedHosts?: string[];
};

Docker Server Deployment

For containerized deployments, configure the server to bind to all interfaces:

{
  server: {
    host: '0.0.0.0',
    port: 8080,
    allowedHosts: ['*']
  }
}

Sources: config.d.ts:117-130

Architecture Overview

graph TD
    A[Developer Machine] --> B[Docker Container]
    B --> C[Playwright MCP Server]
    C --> D[Browser Instance]
    D --> E[Web Application]
    
    F[CI/CD Pipeline] --> B
    G[External Client] --> |HTTP:8080| B
    
    style B fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#fff3e0

Deployment Workflow

graph LR
    A[Build Image] --> B[Create Container]
    B --> C[Run Tests or Server]
    C --> D{Pass?}
    D -->|Yes| E[Success]
    D -->|No| F[Debug & Fix]
    F --> A
    
    G[Clean Up] --> H[Remove Container]
    G --> I[Remove Image]

Environment Variables

Sources: CONTRIBUTING.md:58-60 Sources: playwright.config.ts:13

Complete Docker Workflow Example

# 1. Build the Docker image
npm run docker-build

# 2. Remove any existing container
npm run docker-rm

# 3. Run the container
npm run docker-run

# 4. In another terminal, run Docker-specific tests
MCP_IN_DOCKER=1 npm run dtest

# 5. Clean up when done
npm run docker-rm

Limitations and Considerations

1. No Dockerfile in Repository: The repository does not include a Dockerfile. Users must create their own based on project requirements.
2. Browser Installation: When building custom Docker images, ensure browsers are installed using npx playwright install.
3. Port Mapping: The default configuration exposes port 8080; adjust as needed for your environment.
4. Browser Compatibility: Docker testing is limited to Chromium (chromium-docker project).

Sources: CLAUDE.md:11-16

Related Configuration

Related Pages

Related topics: Docker Deployment, MCP Client Integration

Programmatic Usage

This page documents how to programmatically use Playwright MCP (Model Context Protocol) to integrate Playwright browser automation capabilities into your applications.

Overview

Playwright MCP provides browser automation tools that can be used by Large Language Models (LLMs) through the MCP protocol. The package exposes a createConnection function that enables programmatic integration with MCP-compatible clients.

The core implementation resides in the Playwright monorepo, while this repository serves as the distribution package for the MCP tools.

Sources: src/README.md:1-3

Entry Points

Playwright MCP provides two primary entry points for programmatic usage:

Sources: index.js:1-30 Sources: cli.js:1-45

Module Import

The primary module export provides the createConnection function:

const { createConnection } = require('@playwright/mcp');

Sources: index.js:27-29

The createConnection function is sourced from playwright-core/lib/coreBundle, which contains the core MCP implementation including tool definitions and connection handling logic.

CLI Usage

The CLI can be invoked directly via Node.js:

node cli.js [command] [options]

The CLI is decorated with Playwright's MCP command utilities, which handle transport negotiation and tool invocation.

Sources: cli.js:24-28

Configuration

Playwright MCP accepts configuration through the Config type defined in config.d.ts.

Tool Capabilities

Tool capabilities define which browser automation features are enabled:

export type ToolCapability =
  | 'config'
  | 'core'
  | 'core-navigation'
  | 'core-tabs'
  | 'core-input'
  | 'core-install'
  | 'network'
  | 'pdf'
  | 'storage'
  | 'testing'
  | 'vision'
  | 'devtools';

Sources: config.d.ts:17-30

Browser Configuration

browser?: {
  browserName?: 'chromium' | 'firefox' | 'webkit';
  isolated?: boolean;
  userDataDir?: string;
  launchOptions?: object;
}

Sources: config.d.ts:32-56

Timeout Configuration

timeouts?: {
  action?: number;      // Default: 5000ms
  navigation?: number;  // Default: 60000ms
  expect?: number;       // Default: 5000ms
}

Sources: config.d.ts:98-110

Server Configuration

server?: {
  port?: number;
  host?: string;
  allowedHosts?: string[];
}

Sources: config.d.ts:146-156

Architecture

graph TD
    A[Client Application] -->|MCP Protocol| B[playwright-mcp]
    B --> C[createConnection]
    C --> D[playwright-core]
    D --> E[Browser Automation]
    E --> F[Chromium]
    E --> G[Firefox]
    E --> H[WebKit]
    
    I[CLI User] -->|cli.js| B
    J[Module User] -->|index.js| B

Available NPM Scripts

The package.json defines the following scripts for working with Playwright MCP:

Sources: package.json:13-24

Package Metadata

Sources: package.json:1-16

Browser Installation

Playwright MCP supports an install-browser command through the CLI:

node cli.js install-browser

This delegates to Playwright's browser installation mechanism, decorated via libCli.decorateProgram.

Sources: cli.js:17-22

Extension Mode

Playwright MCP supports connecting to a running browser instance through the Microsoft Edge/Chrome Playwright Extension:

extension?: boolean;

When enabled, this allows connection to an existing browser instance rather than launching a new one.

Sources: config.d.ts:134-140

Network Configuration

Control browser network access through origin-based filtering:

network?: {
  allowedOrigins?: string[];   // List of allowed origins
  blockedOrigins?: string[];   // List of blocked origins
}

Supported formats:

• Full origin: https://example.com:8080
• Wildcard port: http://localhost:*

Sources: config.d.ts:190-204

Session Management

Sources: config.d.ts:166-173

Console Configuration

console?: {
  level?: 'error' | 'warning' | 'info' | 'debug';
}

Sources: config.d.ts:182-187

Related Pages

Related topics: Browser Configuration, Troubleshooting

User Profiles and Session Management

Overview

User Profiles and Session Management in Playwright MCP controls how browser instances are created, persisted, and shared across multiple HTTP clients and tool invocations. This system enables sophisticated browser automation scenarios while maintaining security and resource efficiency.

The MCP server supports:

• Isolated browser instances per request
• Persistent user data directories for profile retention
• Shared browser contexts across clients
• Session saving and restoration
• Secrets masking in responses

Sources: config.d.ts:22-40

Architecture

graph TD
    A[MCP Client] -->|HTTP/STDIO| B[Playwright MCP Server]
    B --> C[Browser Manager]
    C --> D{Shared Context?}
    D -->|Yes| E[Single Browser Context]
    D -->|No| F[Per-Client Context]
    E --> G[Browser Instance]
    F --> G
    G --> H[User Data Directory]
    G --> I[Session Files]
    H -->|Persistence| J[Output Directory]

Core Components

Sources: config.d.ts:1-50

Browser Configuration

Browser Type Selection

The MCP server supports three browser engines:

browser?: {
  browserName?: 'chromium' | 'firefox' | 'webkit';
}

Sources: config.d.ts:24-30

User Data Directory

The user data directory stores browser profile data including cookies, local storage, and session state.

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

Behavior:

• When userDataDir is unspecified, a temporary directory is created automatically
• Persistent directories survive browser restarts
• Useful for maintaining login sessions across tool invocations

Sources: config.d.ts:38-43

Isolated Mode

When isolated: true, browser profiles are kept entirely in memory without disk persistence.

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

Sources: config.d.ts:32-37

Session Management

Session Saving

The saveSession option controls whether Playwright sessions are persisted to the output directory.

export type Config = {
  /**
   * Whether to save the Playwright session into the output directory.
   */
  saveSession?: boolean;
}

Use cases:

• Debugging failed automation workflows
• Resuming interrupted sessions
• Analyzing browser state post-execution

Sources: config.d.ts:83-87

Output Directory

Sessions and output files are saved to the configured output directory.

export type Config = {
  /**
   * The directory to save output files.
   */
  outputDir?: string;
}

Default behavior: If not specified, the MCP server uses a platform-specific temporary directory.

Sources: config.d.ts:95-99

Browser Context Management

Shared Browser Context

When multiple HTTP clients connect to the MCP server, sharedBrowserContext determines whether they share a single browser context or receive isolated contexts.

export type Config = {
  /**
   * Reuse the same browser context between all connected HTTP clients.
   */
  sharedBrowserContext?: boolean;
}

graph LR
    A[Client 1] -->|MCP| B{sharedBrowserContext}
    C[Client 2] -->|MCP| B
    D[Client N] -->|MCP| B
    
    B -->|true| E[Shared Context]
    B -->|false| F[Client 1 Context]
    B -->|false| G[Client 2 Context]
    B -->|false| H[Client N Context]

Sources: config.d.ts:89-94

Secrets Management

The secrets system prevents sensitive data from being exposed to LLM clients.

export type Config = {
  /**
   * Secrets are used to replace matching plain text in the tool responses to prevent the LLM
   * from accidentally getting sensitive data. It is a convenience and not a security feature,
   * make sure to always examine information coming in and from the tool on the client.
   */
  secrets?: Record<string, string>;
}

Key characteristics:

• Not a security feature - Use proper authentication for actual security
• Pattern matching replaces plain text in responses
• Prevents LLM accidental exposure of sensitive information

Sources: config.d.ts:100-106

Configuration Schema

Complete Config Type

export type Config = {
  browser?: {
    browserName?: 'chromium' | 'firefox' | 'webkit';
    isolated?: boolean;
    userDataDir?: string;
    // ... launch options
  };
  
  capabilities?: ToolCapability[];
  saveSession?: boolean;
  sharedBrowserContext?: boolean;
  secrets?: Record<string, string>;
  outputDir?: string;
  
  console?: {
    level?: 'error' | 'warning' | 'info' | 'debug';
  };
  
  network?: {
    allowedOrigins?: string[];
    blockedOrigins?: string[];
  };
  
  testIdAttribute?: string;
  
  timeouts?: {
    action?: number;
    navigation?: number;
    expect?: number;
  };
  
  imageResponses?: 'allow' | 'omit';
  
  // ... additional options
};

Sources: config.d.ts:1-180

Tool Capabilities

The MCP server exposes browser automation through categorized tool capabilities:

Sources: config.d.ts:13-26

Server Configuration

The MCP server uses STDIO transport by default for optimal integration with MCP clients.

{
  "name": "io.github.microsoft/playwright-mcp",
  "description": "Playwright Tools for MCP",
  "version": "0.0.75",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@playwright/mcp",
      "version": "0.0.75",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

Sources: server.json:1-15

CLI Options

The MCP server can be configured via command-line arguments:

node cli.js --help

Key CLI commands:

• install-browser - Install required browser binaries
• Standard Playwright CLI options for browser management

Sources: cli.js:1-35

Best Practices

Security Recommendations

1. Do not rely on secrets masking for security - Treat it as UI/UX convenience only
2. Use isolated mode for untrusted content
3. Configure network restrictions using allowedOrigins and blockedOrigins

Performance Optimization

Testing Workflow

For testing MCP functionality:

# Fast path - Chromium only
npm run ctest

# Full test suite - All browsers
npm run mcp-test

# Docker environment
npm run dtest

Sources: package.json:18-25

Rolling Updates

The Playwright version can be updated while maintaining configuration compatibility:

npm run roll

This command:

1. Updates playwright, playwright-core, and @playwright/test versions
2. Refreshes config.d.ts from the Playwright monorepo
3. Regenerates the README documentation

Sources: roll.js:1-40, CLAUDE.md:1-35

Related Pages

Related topics: User Profiles and Session Management, Browser Configuration

Troubleshooting

This page documents common issues, debugging strategies, and resolution steps when working with Playwright MCP.

Overview

Troubleshooting in Playwright MCP primarily involves:

• Test execution failures
• Browser launch and context issues
• MCP tool invocation problems
• Configuration mismatches
• Dependency and version compatibility

Common Issues and Resolutions

Test Failures

#### All Tests Failing

If all tests fail, verify the test environment is properly configured:

# Ensure dependencies are installed
npm ci

# Install Playwright browsers
npx playwright install

# Run tests in a single browser (faster feedback)
npm run ctest

Source: package.json:11

#### Cross-Browser Test Inconsistencies

Playwright MCP tests run in Chromium, Firefox, and WebKit. If failures occur in specific browsers:

# Test individual browsers
npm run ctest   # Chrome only
npm run ftest   # Firefox only
npm run wtest   # WebKit only

Tests should be hermetic and work on all three platforms: macOS, Linux, and Windows. Sources: CONTRIBUTING.md:71-72

Browser Launch Issues

#### Persistent Context Problems

The isolated option controls whether browser profiles are saved to disk:

{
  browser: {
    isolated: true   // Keeps profile in memory
  }
}

Default behavior creates temporary directories for user data. Sources: config.d.ts:35-38

#### Network Requests Blocked

Configure allowed and blocked origins in the network section:

{
  network: {
    allowedOrigins: ['https://example.com:8080'],
    blockedOrigins: ['https://ads.example.com']
  }
}

Origins matching both lists will be blocked. Sources: config.d.ts:100-112

MCP Tool Invocation Errors

#### Tool Not Found

MCP tools are exposed through the connection interface. Ensure the server is properly initialized:

const { createConnection } = require('@playwright/mcp');

The createConnection function is exported from the core bundle. Sources: index.js:27-28

Configuration Schema Errors

TypeScript errors related to Config type indicate schema mismatches. The config.d.ts file defines the expected structure:

export type Config = {
  browser?: { ... };
  timeouts?: { ... };
  capabilities?: ToolCapability[];
  secrets?: Record<string, string>;
  outputDir?: string;
  console?: { level?: 'error' | 'warning' | 'info' | 'debug' };
  network?: { allowedOrigins?: string[]; blockedOrigins?: string[] };
}

Debugging Strategies

Enabling Debug Logs

Configure console log levels to control verbosity:

{
  console: {
    level: 'debug'  // 'error' | 'warning' | 'info' | 'debug'
  }
}

Default level is 'info'. Sources: config.d.ts:88-91

Timeouts Configuration

Adjust timeouts for slow environments:

{
  timeouts: {
    action: 10000,     // Default: 5000ms
    navigation: 120000, // Default: 60000ms
    expect: 10000      // Default: 5000ms
  }
}

Sources: config.d.ts:64-77

Saving Sessions for Analysis

Enable saveSession to persist Playwright session data for debugging:

{
  saveSession: true
}

Sessions are saved to the configured outputDir. Sources: config.d.ts:81-84

Docker Environment Issues

When running tests in Docker containers:

# Build Docker image
npm run docker-build

# Run container
npm run docker-run

# Execute tests in Docker
npm run dtest

Docker tests run with MCP_IN_DOCKER=1 environment variable. Sources: package.json:16-18

Version Rollback Problems

If rolling Playwright causes issues:

1. The roll.js script updates dependencies and regenerates configuration
2. After running npm run roll, always run tests before committing

npm run roll
npm test  # Must pass before proceeding

If tests fail after a roll, revert changes and investigate the version bump. Sources: CLAUDE.md:12-14

Contributing Troubleshooting

PR Closed Without Review

Unsolicited PRs: Pull requests submitted without a linked issue or prior approval will be closed. Sources: CONTRIBUTING.md:29-30

Always file an issue first before submitting changes.

Linting Failures

Run the linter before submitting:

npm run lint

This also regenerates the README documentation. Sources: package.json:9

Workflow Diagram

graph TD
    A[Start] --> B{Issue?</B]
    B -->|Yes| C[File GitHub Issue]
    B -->|No| D[Check Existing Issues]
    C --> E{Assigned?}
    D --> E
    E -->|Yes| F[Create Branch]
    E -->|No| G[Wait for Assignment]
    G --> E
    F --> H[Make Changes]
    H --> I[Add Tests]
    I --> J[Run Tests]
    J -->|Pass| K[Run Linter]
    J -->|Fail| L[Debug & Fix]
    L --> J
    K -->|Pass| M[Commit Changes]
    K -->|Fail| N[Fix Lint Errors]
    N --> K
    M --> O[Open PR]

Quick Reference Commands

Getting Help

If issues persist after following this guide:

1. Search existing GitHub Issues
2. Check the Playwright Documentation
3. Review the main Playwright repository for upstream issues

The core of Playwright MCP was moved to the Playwright monorepo. Sources: CONTRIBUTING.md:23-24

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Project risk: Project risk needs validation

• Severity: medium
• Finding: Project risk is backed by a source signal: Project risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: identity.distribution | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | repo=playwright-mcp; install=@playwright/mcp@latest

2. Installation risk: Bad entrypoint in docker example

• Severity: medium
• Finding: Installation risk is backed by a source signal: Bad entrypoint in docker example. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/issues/1609

3. Installation risk: v0.0.72

• Severity: medium
• Finding: Installation risk is backed by a source signal: v0.0.72. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.72

4. Configuration risk: v0.0.69

• Severity: medium
• Finding: Configuration risk is backed by a source signal: v0.0.69. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.69

5. Configuration risk: v0.0.71

• Severity: medium
• Finding: Configuration risk is backed by a source signal: v0.0.71. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.71

6. Configuration risk: v0.0.73

• Severity: medium
• Finding: Configuration risk is backed by a source signal: v0.0.73. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.73

7. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:952688112 | https://github.com/microsoft/playwright-mcp | README/documentation is current enough for a first validation pass.

8. Project risk: [Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening af…

• Severity: medium
• Finding: Project risk is backed by a source signal: [Bug] Running multiple parallel async browsers in --isolated mode leaves orphan browsers. This has started happening af…. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/issues/1607

9. Project risk: v0.0.67

• Severity: medium
• Finding: Project risk is backed by a source signal: v0.0.67. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.67

10. Project risk: v0.0.68

• Severity: medium
• Finding: Project risk is backed by a source signal: v0.0.68. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.68

11. Project risk: v0.0.74

• Severity: medium
• Finding: Project risk is backed by a source signal: v0.0.74. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.74

12. Project risk: v0.0.75

• Severity: medium
• Finding: Project risk is backed by a source signal: v0.0.75. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.75

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using playwright-mcp with real data or production workflows.

• [[Feature Request] Support clientCertificates option for mTLS authenticat](https://github.com/microsoft/playwright-mcp/issues/1456) - github / github_issue
• [[Disclosure] Clarify browser/network action boundary in Playwright MCP s](https://github.com/microsoft/playwright-mcp/issues/1617) - github / github_issue
• [[Bug]: Windows taskkill output can pollute MCP stdio transport](https://github.com/microsoft/playwright-mcp/issues/1611) - github / github_issue
• [[Bug] Running multiple parallel async browsers in --isolated mode leaves](https://github.com/microsoft/playwright-mcp/issues/1607) - github / github_issue
• VS Code installation buttons don't seem to work - github / github_issue
• Bad entrypoint in docker example - github / github_issue
• v0.0.75 - github / github_release
• v0.0.74 - github / github_release
• v0.0.73 - github / github_release
• v0.0.72 - github / github_release
• v0.0.71 - github / github_release
• v0.0.69 - github / github_release