Related Pages

Related topics: Getting Started, Architecture Overview

Project Introduction

The Playwright MCP Server (mcp-playwright) is a Model Context Protocol (MCP) server implementation that provides browser automation capabilities through Playwright. It enables AI assistants like Claude, Cursor, and other MCP-compatible clients to interact with web pages through a standardized tool interface.

Overview

The project serves as a bridge between AI assistants and browser automation, exposing Playwright's browser control capabilities as MCP tools. This allows AI agents to perform web navigation, content extraction, form interactions, and other browser-related tasks using natural language commands.

Key Characteristics:

Sources: package.json:1-20

Architecture

The server follows a client-server architecture where AI assistants act as MCP clients communicating with the Playwright MCP server.

graph TD
    A["AI Assistant<br/>(Claude, Cursor, etc.)"] -->|MCP Protocol| B["Playwright MCP Server"]
    B -->|stdin/stdout| A
    B -->|HTTP/SSE| B
    C["Browser Instances<br/>(Chromium, Firefox, WebKit)"] -->|Playwright API| B
    
    B -->|Browser Automation| C
    C -->|Page Content| B
    B -->|Tool Results| A

Core Components

Sources: src/logging/middleware.ts:1-20

Installation Methods

The project supports multiple installation approaches to accommodate different deployment scenarios.

Package Managers

# npm
npm install -g @executeautomation/playwright-mcp-server

# mcp-get
npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server

# Smithery (automated)
npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude

Claude Code

claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server

Sources: README.md:40-65

Operation Modes

The server supports two primary operation modes based on the transport mechanism.

STDIO Mode (Default)

STDIO mode is the recommended configuration for Claude Desktop and other clients that communicate via standard input/output streams.

graph LR
    A["MCP Client"] -->|"stdio"| B["Playwright MCP Server"]
    B -->|"stdio"| A
    C["Playwright<br/>Browser"] -->|Control| B

Configuration Example:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

Note: In stdio mode, logging is automatically directed to files only to maintain clean JSON-RPC communication. Logs are written to ~/playwright-mcp-server.log.

Sources: README.md:20-30

HTTP Mode (Standalone Server)

HTTP mode enables the server to run as a standalone HTTP server, suitable for VS Code, custom clients, and remote deployments.

npx @executeautomation/playwright-mcp-server --port 8931

Available Endpoints:

Client Configuration:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Sources: README.md:35-55 Sources: examples/http-mode-example.md:1-30

Docker Deployment

The project provides official Docker images for containerized deployments.

Basic Usage

docker run -i --rm mcp-playwright:latest

Docker Configuration

{
  "mcpServers": {
    "playwright-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
    }
  }
}

Environment Variables

Volume Mounts

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  -v $(screenshots):/app/screenshots \
  mcp-playwright:latest

Note: The Docker image skips browser downloads by default to reduce size (~200MB). Browsers are downloaded on first use.

Sources: DOCKER.md:1-80

Supported Tools

The server exposes a comprehensive set of Playwright operations as MCP tools.

Browser Control Tools

Browser Support

Sources: CHANGELOG.md:1-30

Dependencies

Production Dependencies

Development Dependencies

Sources: package.json:20-50

Logging System

The server includes a comprehensive logging system for debugging and monitoring.

Log Location

• STDIO Mode: ~/playwright-mcp-server.log (file only)
• HTTP Mode: Configurable via server settings

Log Features

Sources: src/logging/logger.ts:1-50 Sources: src/logging/middleware.ts:1-30

Troubleshooting

Common Issues

Important: When adding new tools, ensure tool names are short enough to not exceed the 60-character limit for combined server and tool name (server_name:tool_name). The server name is playwright-mcp.

Sources: README.md:15-18

Version History

Sources: CHANGELOG.md:1-50

Next Steps

For more detailed information, refer to:

• Installation Guide - Detailed setup instructions
• API Reference - Complete tool documentation
• Device Quick Reference - Mobile device emulation
• Prompt Guide - Resize prompt strategies

Related Pages

Related topics: Project Introduction, Docker Deployment, Configuration Guide

Getting Started

This guide provides everything you need to install, configure, and run the Playwright MCP Server. The server enables AI assistants like Claude to interact with web browsers through a comprehensive set of automation tools.

Overview

The Playwright MCP Server is a Model Context Protocol (MCP) server that provides programmatic control over Playwright browsers. It allows AI assistants to perform web automation tasks including navigation, interaction, content extraction, and screenshot capture.

Key Features:

• Multi-browser support (Chromium, Firefox, WebKit)
• 143 device presets for mobile emulation
• Screenshot and PDF generation
• Web scraping and content extraction
• Keyboard and mouse automation
• HTTP and stdio communication modes

Sources: README.md:1-45

Prerequisites

Before installing the Playwright MCP Server, ensure your system meets these requirements:

System Dependencies for Playwright:

• Linux: npx playwright install-deps
• macOS: Xcode Command Line Tools
• Windows: Visual Studio Build Tools

Sources: package.json:23-36

Installation Methods

Method 1: npm Package (Recommended)

Install the package globally for CLI access:

npm install -g @executeautomation/playwright-mcp-server

Or use it directly with npx (no installation required):

npx -y @executeautomation/playwright-mcp-server

Sources: README.md:56-65

Method 2: Docker Container

Pull the pre-built image from Docker Hub:

docker pull mcp-playwright:latest

Or build from source:

git clone https://github.com/executeautomation/mcp-playwright.git
cd mcp-playwright
docker build -t mcp-playwright:latest .

The Docker image is approximately 200MB (without browsers) and uses a Debian-based slim Node.js image.

Sources: DOCKER.md:80-100

Configuration

Claude Desktop

Edit your Claude Desktop configuration file:

File Locations:

stdio Mode (Default):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

Sources: README.md:56-65

VS Code MCP Extension

For VS Code with the MCP extension, add this to your MCP settings:

{
  "name": "playwright",
  "command": "npx",
  "args": ["-y", "@executeautomation/playwright-mcp-server"]
}

Sources: DOCKER.md:12-20

Docker Configuration

Basic Configuration:

{
  "mcpServers": {
    "playwright-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
    }
  }
}

With Environment Variables:

docker run -i --rm \
  -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
  -e NODE_ENV=production \
  mcp-playwright:latest

With Volume Mounts:

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/screenshots:/app/screenshots \
  mcp-playwright:latest

Sources: DOCKER.md:1-50

Running Modes

stdio Mode (Interactive)

The default mode for Claude Desktop where the server communicates via stdin/stdout:

# Using npx
npx -y @executeautomation/playwright-mcp-server

# Using global installation
playwright-mcp-server

In stdio mode, logs are automatically directed to files only (~/playwright-mcp-server.log) to maintain clean JSON-RPC communication.

Sources: README.md:56-65

HTTP Mode (Standalone Server)

For VS Code, custom clients, or remote deployments where you need a headed browser:

# Using npx
npx @executeautomation/playwright-mcp-server --port 8931

# Using global installation
playwright-mcp-server --port 8931

HTTP Mode Endpoints:

Security Note: The HTTP server binds to localhost only (127.0.0.1) to prevent external access. For remote access, use SSH tunneling.

Sources: README.md:67-90 Sources: src/http-server.ts:1-50

Claude Desktop HTTP Configuration:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Sources: examples/http-mode-example.md:1-30

Architecture Overview

graph TD
    subgraph "AI Assistant"
        A[Claude / Cursor / VS Code]
    end
    
    subgraph "MCP Client"
        B[MCP SDK Client]
    end
    
    subgraph "Playwright MCP Server"
        C[Transport Layer]
        D[Tool Handlers]
        E[Browser Manager]
    end
    
    subgraph "Playwright"
        F[Chromium]
        G[Firefox]
        H[WebKit]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    E --> G
    E --> H

Available Tools

The server exposes the following tool categories:

Navigation Tools

Interaction Tools

Content Tools

Output Tools

Device Emulation

// Test on iPhone 13
await playwright_resize({ device: "iPhone 13" });

// Test on iPad with landscape
await playwright_resize({ device: "iPad Pro 11", orientation: "landscape" });

// Test desktop
await playwright_resize({ device: "Desktop Chrome" });

Sources: README.md:25-50 Sources: CHANGELOG.md:1-30

First Steps

1. Verify Installation

After configuration, restart your AI client and verify the server is connected:

Health check endpoint (HTTP mode):
curl http://localhost:8931/health

Expected response:

{
  "status": "ok",
  "version": "1.0.10",
  "activeSessions": 0
}

Sources: src/http-server.ts:40-48

2. Basic Browser Operations

Once connected, you can use natural language to control the browser:

"Navigate to https://example.com"
"Take a screenshot"
"Click on the login button"
"Fill in the search box with 'test'"
"Get the page title"

3. Device Emulation

Test responsive designs:

"Test on iPhone 13"
"Switch to iPad Pro view"
"Rotate to landscape"

Sources: README.md:30-45

Troubleshooting

Container Exits Immediately

MCP servers wait for input on stdin. Ensure you're running with the -i flag:

docker run -i --rm mcp-playwright:latest

Sources: DOCKER.md:55-60

Browser Not Found

The Docker image skips browser downloads by default. Create a custom Dockerfile:

FROM mcp-playwright:latest
RUN npx playwright install chromium --with-deps

Sources: DOCKER.md:65-72

Permission Issues with Volumes

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  --user $(id -u):$(id -g) \
  mcp-playwright:latest

Sources: DOCKER.md:75-82

Connection Issues (HTTP Mode)

Sources: README.md:103-110

Logging

The server includes comprehensive logging for debugging:

Log File Location (stdio mode):

~/playwright-mcp-server.log

Logged Information:

• Tool execution requests and responses
• Error categorization (validation, system, resource)
• Request duration metrics
• Memory and uptime statistics

The logger captures:

• Request IDs for traceability
• Sanitized request bodies (sensitive fields redacted)
• Stack traces for errors
• Platform and environment information

Sources: src/logging/logger.ts:1-50 Sources: src/logging/middleware.ts:1-80

Testing

Run the test suite to verify your installation:

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run custom tests
npm run test:custom

Tests are located in src/__tests__ and use Jest with Playwright preset.

Sources: README.md:113-125

Resource Limits (Docker)

Limit CPU and memory usage:

docker run -i --rm \
  --cpus="2.0" \
  --memory="2g" \
  mcp-playwright:latest

Or in docker-compose.yml:

services:
  playwright-mcp:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G

Sources: DOCKER.md:115-130

Next Steps

Related Pages

Related topics: Project Introduction, Transport Modes, Browser Automation Tools

Architecture Overview

Introduction

The mcp-playwright project is a Model Context Protocol (MCP) server that exposes Playwright browser automation capabilities to AI assistants such as Claude. The architecture follows a modular, tool-based design pattern where each browser automation operation is exposed as a discrete tool that MCP clients can invoke through JSON-RPC calls.

The server is designed to operate in two distinct transport modes: stdio mode for direct integration with MCP clients like Claude Desktop, and HTTP mode for remote deployments, VS Code integration, or headless browser scenarios. This dual-mode architecture provides flexibility while maintaining a consistent internal structure for tool registration, execution, and logging.

Sources: README.md:1-20

High-Level Architecture

The architecture consists of four primary layers that work together to process tool requests and execute browser automation tasks.

graph TD
    A[MCP Client<br/>Claude Desktop / VS Code] --> B[Transport Layer<br/>stdio or HTTP]
    B --> C[Request Handler<br/>requestHandler.ts]
    C --> D[Tool Handler<br/>toolHandler.ts]
    D --> E[Tool Registry<br/>tools.ts]
    E --> F[Browser Tools<br/>playwright API]
    F --> G[Chromium / Firefox / WebKit]

The Transport Layer handles the communication protocol, converting between the client's transport mechanism and the internal request format. The Request Handler validates and routes incoming requests to the appropriate tool. The Tool Handler manages tool execution, error handling, and response formatting. Finally, the Browser Tools layer wraps the Playwright API to provide browser automation capabilities.

Sources: src/index.ts

Core Data Structures

The type system defines the fundamental interfaces used throughout the codebase. These types establish the contract between components and ensure type safety across the architecture.

Sources: src/types.ts:1-17

Tool Interface

export interface Tool {
  name: string;
  description: string;
  parameters: {
    type: string;
    properties: Record<string, unknown>;
    required?: string[];
  };
  handler: (args: any) => Promise<any>;
}

The Tool interface represents a single automation capability exposed to MCP clients. Each tool contains a unique name identifier, a human-readable description, a JSON Schema-compatible parameters definition, and an asynchronous handler function that executes the actual automation logic.

ToolCall Interface

export interface ToolCall {
  name: string;
  parameters: Record<string, unknown>;
  result?: CallToolResult;
}

The ToolCall interface tracks the lifecycle of a tool invocation, capturing the tool name, input parameters, and the computed result.

Request Processing Pipeline

The request processing pipeline transforms incoming MCP requests into executed browser automation operations.

graph LR
    A[Incoming Request] --> B[Parse & Validate]
    B --> C[Route to Tool Handler]
    C --> D[Execute Tool Handler]
    D --> E{Check Result}
    E -->|Success| F[Return CallToolResult]
    E -->|Error| G[Log Error Context]
    G --> H[Return Error Response]

Request Handler Component

The request handler acts as the entry point for all incoming requests. It is responsible for parsing the incoming JSON-RPC messages, validating the request structure, and delegating to the appropriate tool handler.

Sources: src/requestHandler.ts

Tool Registration and Management

The tool registry maintains a collection of all available automation tools. New tools are registered through the BROWSER_TOOLS array, which contains all browser-related automation operations.

graph TD
    A[Tool Definition<br/>src/tools/browser/*.ts] --> B[BROWSER_TOOLS Array]
    B --> C[Tool Handler Registration]
    C --> D[MCP Server<br/>Tool List]

Tool Handler

The tool handler manages the execution context for all tools. It provides the following capabilities:

Sources: src/toolHandler.ts

Available Tool Categories

The tools are organized into logical categories based on their function:

Sources: CHANGELOG.md:1-30

Logging and Observability

The logging middleware provides comprehensive observability into tool execution. It captures request context, execution duration, error details, and system metrics.

graph TD
    A[Tool Execution Start] --> B[Generate Request ID]
    B --> C[Log Request Start]
    C --> D[Execute Handler]
    D --> E{Result Type}
    E -->|Success| F[Log Success<br/>Duration: Xms]
    E -->|Error| G[Capture Error Context]
    G --> H[Categorize Error]
    H --> I[Log Error<br/>with Stack Trace]

Error Categorization

The middleware categorizes errors into distinct types for better debugging and monitoring:

Sources: src/logging/middleware.ts:80-120

Request Sanitization

The logging middleware automatically sanitizes sensitive data from tool arguments before logging:

Sources: src/logging/middleware.ts:150-170

Transport Modes

stdio Mode

In stdio mode, the server communicates over standard input and output streams. This mode is designed for direct integration with MCP clients like Claude Desktop.

Sources: README.md:30-45

HTTP Mode

HTTP mode exposes the server as a standalone HTTP server with multiple endpoints:

The default port is 8931, configurable via the --port flag.

Sources: README.md:55-70

graph LR
    A[MCP Client] -->|HTTP POST /mcp| B[HTTP Server]
    B --> C[Request Handler]
    C --> D[Tool Handler]
    D --> E[Browser Automation]
    E --> F[Response]
    F --> B
    B --> A

Browser Context Management

The architecture supports multiple browser engines:

The browserType parameter in playwright_navigate allows selection of the browser engine:

await playwright_navigate({ 
  url: "https://example.com",
  browserType: "firefox"  // chromium, firefox, or webkit
});

Sources: CHANGELOG.md:15-20

Deployment Architecture

Docker Deployment

The Docker deployment provides a containerized environment for the MCP server:

graph TD
    A[Docker Host] --> B[mcp-playwright:latest]
    B --> C[Node.js Runtime]
    C --> D[MCP Server]
    D --> E[Playwright Browsers]
    E --> F[Chromium<br/>Firefox<br/>WebKit]

The Docker image is optimized for size (~200MB without browsers) and supports environment variable configuration:

Sources: DOCKER.md:40-60

Claude Desktop Configuration

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

For HTTP mode with remote deployments:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Sources: README.md:35-40

Related Pages

Related topics: Architecture Overview, Configuration Guide

Transport Modes

The mcp-playwright server supports two distinct transport modes for communicating with MCP clients: STDIO Transport and HTTP/SSE Transport. Each mode serves different deployment scenarios and client requirements.

Overview

The transport mode determines how the MCP protocol messages are exchanged between the Playwright MCP server and connected clients. The server automatically detects the appropriate mode based on command-line arguments or environment configuration.

STDIO Transport Mode

Purpose and Architecture

STDIO (Standard Input/Output) is the default transport mode for MCP servers. It provides process-based communication where messages are exchanged through the parent process's standard input and output streams.

graph LR
    A[MCP Client<br/>Claude Desktop] <-->|stdin/stdout pipes| B[playwright-mcp-server<br/>STDIO Mode]
    B <-->|Playwright API| C[Browser Instance]

How STDIO Mode Works

1. The MCP client spawns the server as a child process
2. JSON-RPC messages are sent via process stdin
3. Responses are received via process stdout
4. The server runs in headless mode by default
5. Logging is automatically redirected to ~/playwright-mcp-server.log

Sources: README.md

Configuration for Claude Desktop

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

Sources: README.md

Docker Considerations

When running in Docker containers, STDIO mode requires the -i flag to keep STDIN open for interactive communication:

docker run -i --rm mcp-playwright:latest

Sources: DOCKER.md

HTTP/SSE Transport Mode

Purpose and Architecture

HTTP/SSE transport runs the MCP server as a standalone HTTP server. This mode is designed for scenarios where STDIO communication is impractical, such as:

• Running headed browsers on headless systems
• Integration with IDE worker processes
• Remote client access via HTTP
• Multi-client concurrent connections

graph TD
    A[MCP Client<br/>VS Code / Custom] -->|HTTP/REST| B[HTTP Server<br/>127.0.0.1:8931]
    B --> C[SSE Transport<br/>Server-Sent Events]
    B --> D[Message Handler<br/>POST /messages]
    C --> E[Session Manager]
    D --> E
    E --> F[Playwright MCP<br/>Tool Handler]
    F --> G[Browser Instance]

Available Endpoints

The HTTP server exposes the following endpoints:

Sources: src/http-server.ts

Starting the HTTP Server

# Using npx
npx @executeautomation/playwright-mcp-server --port 8931

# Or after global installation
npm install -g @executeautomation/playwright-mcp-server
playwright-mcp-server --port 8931

Sources: examples/http-mode-example.md

HTTP Server Output

When started successfully, the server displays:

==============================================
Playwright MCP Server (HTTP Mode)
==============================================
Listening: 127.0.0.1:8931 (localhost only)
Version: <version>

SECURITY: Server is bound to localhost only.
          Not accessible from external networks.

ENDPOINTS:
- SSE Stream:     GET  http://localhost:8931/sse
- Messages:       POST http://localhost:8931/messages?sessionId=<id>
- MCP (unified):  GET  http://localhost:8931/mcp
- MCP (unified):  POST http://localhost:8931/mcp?sessionId=<id>
- Health Check:   GET  http://localhost:8931/health

Sources: src/http-server.ts

Client Configuration

#### Claude Desktop (HTTP)

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

#### VS Code MCP Extension

{
  "name": "playwright",
  "url": "http://localhost:8931/mcp"
}

#### Health Check

curl http://localhost:8931/health

Sources: examples/http-mode-example.md

Security Model

The HTTP server binds exclusively to 127.0.0.1 (localhost) for security reasons:

SECURITY: Server binds to localhost only. Not accessible from external networks.

For remote access, SSH tunneling is recommended:

ssh -L 8931:localhost:8931 user@remote-server

Sources: src/http-server.ts

Mode Selection

Automatic Selection

The server automatically selects the transport mode based on:

1. Presence of --port argument → HTTP/SSE mode
2. Absence of --port argument → STDIO mode

Health Check Response

Example response:

{
  "status": "ok",
  "version": "1.0.10",
  "activeSessions": 2
}

Transport Comparison

Sources: README.md

Logging Behavior

STDIO Mode

• Logging automatically directed to files only
• Console output kept clean for JSON-RPC communication
• Logs written to ~/playwright-mcp-server.log

HTTP Mode

• Standard logging to console and file
• Request/response logging via middleware
• Error context capture including:
• Stack traces
• Memory usage
• Platform information
• Request duration

Sources: src/logging/middleware.ts

Environment Variables

Sources: DOCKER.md

Related Pages

Related topics: Device Emulation, API Testing Tools, Code Generation and Recording

Browser Automation Tools

Overview

The Browser Automation Tools constitute the core module of the mcp-playwright project, providing a comprehensive set of MCP (Model Context Protocol) tools for browser-based web automation and testing. These tools enable AI assistants and automated systems to interact with web pages programmatically, performing actions such as navigation, element interaction, content extraction, and response monitoring.

The module supports multiple browser engines (Chromium, Firefox, WebKit) and provides both headless and headed execution modes, making it suitable for a wide range of automation scenarios from simple web scraping to complex end-to-end testing.

Architecture Overview:

graph TD
    A[MCP Client] -->|JSON-RPC| B[Tool Handler]
    B --> C[Browser Tool Executor]
    C --> D[Browser Engine]
    D --> E[Chromium<br/>Firefox<br/>WebKit]
    
    F[Base Class] -->|Inheritance| C
    F --> G[Error Handling]
    F --> H[Page Validation]
    F --> I[Safe Execution]

Core Components

Tool Architecture

The browser automation tools follow an object-oriented architecture with a base class pattern. All browser tools inherit from BrowserToolBase, which provides common functionality including error handling, page validation, and safe execution wrappers.

Class Hierarchy:

graph TD
    A[BrowserToolBase] --> B[navigation.ts<br/>NavigateTool]
    A --> C[interaction.ts<br/>ClickTool, FillTool, etc.]
    A --> D[screenshot.ts<br/>ScreenshotTool]
    A --> E[console.ts<br/>ConsoleLogsTool]
    A --> F[output.ts<br/>PdfTool]
    A --> G[resize.ts<br/>ResizeTool]
    A --> H[useragent.ts<br/>CustomUserAgentTool]
    A --> I[response.ts<br/>ExpectResponseTool, AssertResponseTool]
    A --> J[visiblePage.ts<br/>VisibleTextTool, VisibleHtmlTool]
    
    K[ToolContext] --> A
    L[Browser, Page] --> A

Base Class (BrowserToolBase)

The BrowserToolBase class provides the foundation for all browser tools:

File Reference: src/tools/browser/base.ts

Browser Tools Registry

All browser-requiring tools are registered in the BROWSER_TOOLS array and exposed through the MCP tool interface:

File Reference: src/tools/browser/index.ts, src/tools.ts

export const BROWSER_TOOLS = [
  "playwright_navigate",
  "playwright_screenshot",
  "playwright_click",
  "playwright_iframe_click",
  "playwright_iframe_fill",
  "playwright_fill",
  "playwright_select",
  "playwright_hover",
  "playwright_evaluate",
  "playwright_console_logs",
  "playwright_close",
  "playwright_get_visible_text",
  "playwright_get_visible_html",
  "playwright_click_and_switch_tab",
  "playwright_drag",
  "playwright_press_key",
  "playwright_save_as_pdf"
];

Navigation Tools

Navigate Tool (`playwright_navigate`)

The primary navigation tool for loading web pages in the browser.

Parameters:

Multi-Browser Support:

Starting from version 1.0.2, the navigate tool supports specifying the browser type:

Multi-Browser Support: Firefox and WebKit in addition to Chromium

New browserType parameter for playwright_navigate tool

Supported browser types: "chromium" (default), "firefox", "webkit"

Sources: CHANGELOG.md

File Reference: src/tools/browser/navigation.ts

Interaction Tools

Interaction tools enable programmatic control over browser elements, including clicking, filling forms, hovering, and keyboard input.

Click Tool (`playwright_click`)

Clicks an element identified by a CSS selector.

Parameters:

Fill Tool (`playwright_fill`)

Fills input fields with text content.

Parameters:

Select Tool (`playwright_select`)

Selects options in dropdown menus (select elements).

Parameters:

Hover Tool (`playwright_hover`)

Hovers over an element.

Parameters:

Keyboard Interaction

Drag Tool (playwright_drag):

Press Key Tool (playwright_press_key):

iFrame Interaction

The project supports interaction with elements inside iframes through dedicated tools:

File Reference: src/tools/browser/interaction.ts

Screenshot Tools

Screenshot Tool (`playwright_screenshot`)

Captures screenshots of the current page or specific elements.

Parameters:

File Reference: src/tools/browser/screenshot.ts

Content Extraction Tools

Visible Text Tool (`playwright_get_visible_text`)

Extracts visible text content from the page or specific elements.

Parameters:

Visible HTML Tool (`playwright_get_visible_html`)

Retrieves HTML content from the page or elements.

Parameters:

Content Filtering Pipeline:

graph LR
    A[Raw HTML] --> B{removeScripts?}
    B -->|Yes| C[Remove script tags]
    B -->|No| D[Continue]
    C --> E{removeStyles?}
    E -->|Yes| F[Remove style tags]
    E -->|No| G[Continue]
    F --> H{removeMeta?}
    H -->|Yes| I[Remove meta tags]
    H -->|No| J[Continue]
    I --> K{removeComments?}
    K -->|Yes| L[Remove comments]
    K -->|No| M[Continue]
    L --> N{minify?}
    M --> N
    N -->|Yes| O[Minify HTML]
    N -->|No| P[Return Clean HTML]

File Reference: src/tools/browser/visiblePage.ts

Output Tools

PDF Generation Tool (`playwright_save_as_pdf`)

Saves the current page as a PDF document.

Parameters:

File Reference: src/tools/browser/output.ts

Console Tools

Console Logs Tool (`playwright_console_logs`)

Retrieves console messages from the browser page.

Parameters:

Console Message Types:

File Reference: src/tools/browser/console.ts

Response Monitoring Tools

Expect Response Tool (`playwright_expect_response`)

Sets up expectations for network responses.

Parameters:

Assert Response Tool (`playwright_assert_response`)

Asserts that a network response meets specified criteria.

Parameters:

File Reference: src/tools/browser/response.ts

Viewport and Device Emulation

Resize Tool (`playwright_resize`)

Configures viewport dimensions and enables device emulation.

Parameters:

Device Emulation Features:

• 143 real device presets including iPhone, iPad, Pixel, Galaxy, and Desktop browsers
• Automatic user-agent string configuration
• Touch event support emulation
• Device pixel ratio configuration

Natural Language Support:

AI assistants can use natural language prompts such as:

• "Test on iPhone 13"
• "Switch to iPad view"
• "Rotate to landscape"

File Reference: src/tools/browser/resize.ts

User Agent Tools

Custom User Agent Tool (`playwright_custom_user_agent`)

Sets a custom user agent string for the browser context.

Parameters:

File Reference: src/tools/browser/useragent.ts

Browser Lifecycle Management

Close Tool (`playwright_close`)

Closes the current browser context and page.

Parameters:

Error Handling

The browser tools implement comprehensive error handling through the middleware system:

Error Categories:

Enhanced Error Context:

The logging middleware captures detailed error context including:

• Error name and message
• Stack trace
• Timestamp
• Node.js version and platform
• Memory usage statistics
• Browser state information

File Reference: src/logging/middleware.ts

Tool Execution Flow

Complete Tool Execution Pipeline:

sequenceDiagram
    participant Client
    participant MCP_Server
    participant Middleware
    participant Tool
    participant Browser
    
    Client->>MCP_Server: Tool Request
    MCP_Server->>Middleware: Intercept Request
    Middleware->>Middleware: Log Start
    Middleware->>Tool: Execute Tool
    Tool->>Browser: Browser Operation
    Browser-->>Tool: Operation Result
    Tool-->>Middleware: Tool Response
    Middleware->>Middleware: Log Completion
    Middleware-->>Client: Response

Summary

The Browser Automation Tools module provides a comprehensive, MCP-compatible interface for browser automation tasks. Key features include:

All tools follow a consistent pattern with base class inheritance, comprehensive error handling, and structured logging for debugging and monitoring purposes.

Related Pages

Related topics: Browser Automation Tools

Device Emulation

Device Emulation is a core feature of the Playwright MCP Server that enables AI assistants and automated testing tools to simulate real-world mobile and desktop devices directly within the browser automation framework. By leveraging Playwright's built-in device descriptor library, the server provides 143 real device presets with accurate viewport dimensions, user-agent strings, touch capabilities, and device pixel ratios.

Overview

The Device Emulation system integrates with the playwright_resize tool to provide a seamless interface for switching between device profiles. When a device preset is selected, the system automatically configures multiple browser properties simultaneously:

• Viewport dimensions for accurate screen rendering
• User-Agent strings for proper server-side device detection
• Touch capabilities for mobile device simulation
• Device pixel ratio for high-DPI display accuracy

Sources: README.md

Architecture

graph TD
    A[AI Assistant / MCP Client] --> B[playwright_resize Tool]
    B --> C{Device Preset?}
    C -->|Yes| D[Lookup in Playwright devices]
    C -->|No| E[Direct Dimensions]
    D --> F[Extract Device Properties]
    F --> G[page.setViewportSize]
    F --> H[page.setExtraHTTPHeaders]
    G --> I[Browser Context Updated]
    H --> I
    E --> G

Component Flow

1. Client Request: The AI assistant or MCP client sends a playwright_resize call with a device parameter
2. Device Lookup: The system searches Playwright's device descriptor library using the provided name
3. Property Extraction: Device properties including viewport, user-agent, mobile flag, touch support, and scale factor are extracted
4. Browser Configuration: Playwright APIs apply the settings to the active page context

Sources: src/tools/browser/resize.ts:17-48

API Reference

Tool: `playwright_resize`

The primary tool for device emulation and viewport control.

#### Parameters

#### Device Preset Detection

The system validates device names against Playwright's device library and returns helpful suggestions if the device is not found:

if (!device) {
  return createErrorResponse(
    `Device "${args.device}" not found. Popular devices: ${popularDevices.join(', ')}. ` +
    `Use playwright.devices to see all ${Object.keys(devices).length} available devices.`
  );
}

Sources: src/tools/browser/resize.ts:36-43

Supported Devices

The Playwright MCP Server includes support for 143 device presets covering major device categories:

Popular Devices

Device Properties Extracted

When using a device preset, the following properties are automatically configured:

// Extract device properties from Playwright's device library
width = device.defaultBrowserViewport.width;
height = device.defaultBrowserViewport.height;
userAgent = device.defaultUserAgent;
isMobile = device.defaultBrowserType === 'mobile';
hasTouch = device.hasTouch;
deviceScaleFactor = device.deviceScaleFactor || 1;

Sources: src/tools/browser/resize.ts:48-54

Orientation Support

Device emulation supports both portrait and landscape orientations. When an orientation is specified with a device preset, the width and height values are swapped:

// Portrait orientation (default)
await playwright_resize({ device: "iPhone 13", orientation: "portrait" });

// Landscape orientation
await playwright_resize({ device: "iPad Pro 11", orientation: "landscape" });

Orientation Logic

graph LR
    A[Device Preset] --> B{orientation === "landscape"}
    B -->|Yes| C[Swap width ↔ height]
    B -->|No| D[Keep original dimensions]
    C --> E[Apply to Viewport]
    D --> E

The orientation parameter is validated to ensure it is only used with device presets:

if (args.orientation && !args.device) {
  throw new Error("Orientation can only be set when using a device preset");
}

Sources: src/tools/browser/resize.ts:71-74

Validation Rules

The device emulation system enforces several validation constraints:

Dimension Constraints

Parameter Constraints

Sources: src/tools/browser/resize.ts:81-91

Natural Language Support

The device emulation system is designed to work seamlessly with AI assistants that use natural language commands. Common prompt patterns include:

• "Test on iPhone 13"
• "Switch to iPad view"
• "Rotate to landscape"
• "Test desktop view"

These natural language commands are interpreted by the AI assistant and translated into playwright_resize tool calls with the appropriate device and orientation parameters.

Sources: README.md

Implementation Details

Base Class Integration

The ResizeTool extends BrowserToolBase, which provides the foundation for browser interaction:

export class ResizeTool extends BrowserToolBase {
  async execute(args: any, context: ToolContext): Promise<ToolResponse> {
    return this.safeExecute(context, async (page) => {
      // Device emulation logic
    });
  }
}

Error Handling

The implementation uses a safe execution pattern with comprehensive error handling:

private categorizeError(error: Error): 'validation' | 'system' | 'unknown' {
  const message = error.message.toLowerCase();
  
  if (message.includes('invalid') || message.includes('validation') || message.includes('required')) {
    return 'validation';
  }
  
  if (message.includes('browser') || message.includes('page') || message.includes('connection')) {
    return 'system';
  }
  
  return 'unknown';
}

Sources: src/tools/browser/resize.ts:7-11 Sources: src/logging/middleware.ts

Response Format

Success Response

When device emulation is successfully applied, the response includes:

Browser viewport resized to iPhone 13 (390x844) [mobile, touch, 3x scale]

The response includes:

• Device name and dimensions
• Orientation (if specified)
• Applied features: mobile, touch, device scale factor

Error Response

If device emulation fails, an error response is returned with:

• Specific error message explaining the failure
• Suggestions for popular devices when device name is not found
• Reference to available device count

Sources: src/tools/browser/resize.ts:95-120

Tool Registration

The playwright_resize tool is registered in the central tools registry:

{
  name: "playwright_resize",
  description: "Resize browser viewport with optional device emulation",
  inputSchema: {
    type: "object",
    properties: {
      device: { type: "string", description: "Device preset name" },
      width: { type: "number", description: "Viewport width in pixels" },
      height: { type: "number", description: "Viewport height in pixels" },
      orientation: { type: "string", description: "Device orientation" }
    }
  }
}

Sources: src/tools.ts

Dependencies

The device emulation feature relies on the following package dependencies:

Sources: package.json

Usage Examples

Basic Device Emulation

// Test on iPhone 13
await playwright_resize({ device: "iPhone 13" });

// Result: Browser viewport resized to iPhone 13 (390x844) [mobile, touch, 2x scale]

Landscape Orientation

// iPad in landscape mode
await playwright_resize({ device: "iPad Pro 11", orientation: "landscape" });

// Result: Browser viewport resized to iPad Pro 11 (1194x834) in landscape orientation [mobile, touch, 2x scale]

Desktop Browser

// Switch to desktop Chrome view
await playwright_resize({ device: "Desktop Chrome" });

// Result: Browser viewport resized to Desktop Chrome (1280x720)

Custom Dimensions

// Direct viewport control without device preset
await playwright_resize({ width: 1920, height: 1080 });

// Result: Browser viewport resized to 1920x1080

Integration with Other Tools

Device emulation settings persist across multiple tool calls within a session. Other tools that may interact with device emulation include:

The viewport and user-agent settings remain active until explicitly changed by another playwright_resize call.

Sources: src/tools/browser/visiblePage.ts Sources: src/tools/browser/screenshot.ts

Related Pages

Related topics: Browser Automation Tools, Code Generation and Recording

API Testing Tools

Overview

The API Testing Tools module in MCP Playwright provides a comprehensive framework for executing and validating HTTP API requests directly within the Model Context Protocol server environment. This module enables AI assistants and automated testing systems to perform REST API testing operations with full request/response tracking, assertion capabilities, and detailed logging support.

The API Testing Tools extend the MCP Playwright server's functionality beyond browser automation to include robust HTTP client capabilities. This allows for seamless integration of API testing workflows alongside browser-based UI testing, enabling end-to-end testing scenarios that span both frontend and backend interactions.

Architecture

High-Level Architecture

graph TD
    A[MCP Client Request] --> B[Tool Router]
    B --> C[API Testing Module]
    C --> D[Request Executor]
    D --> E[HTTP Client]
    E --> F[External API]
    F --> G[Response Handler]
    G --> H[Assertion Engine]
    H --> I[Tool Response]
    D --> J[Logging Middleware]
    J --> K[Request Logs]
    
    L[Request Builder] --> D
    M[Auth Handler] --> L
    N[Header Manager] --> L

Module Structure

The API Testing Tools are organized into three primary components following the project's modular architecture pattern:

Core Components

API Tool Base Class

The base class for all API tools provides common functionality that mirrors the browser tool architecture while adapting for HTTP operations. This design ensures consistency with the broader MCP Playwright tool framework.

// Pattern inherited from browser base architecture
export abstract class ApiToolBase implements ToolHandler {
  protected server: any;
  
  constructor(server: any) {
    this.server = server;
  }
  
  abstract execute(args: any, context: ToolContext): Promise<ToolResponse>;
  
  protected ensureContext(context: ToolContext): ApiContext | null;
  protected validateRequest(args: any): ToolResponse | null;
  protected safeExecute(context: ToolContext, operation: ...): Promise<ToolResponse>;
}

Sources: src/tools/api/base.ts

Tool Registry and Handler

The API module registers its tools with the MCP server through the standard tool handler interface defined in the types system:

export interface Tool {
  name: string;
  description: string;
  parameters: {
    type: string;
    properties: Record<string, unknown>;
    required?: string[];
  };
  handler: (args: any) => Promise<any>;
}

Sources: src/types.ts:1-15

Request Builder and Executor

The request handler component manages the construction and execution of HTTP requests, supporting various HTTP methods and authentication mechanisms.

Sources: src/tools/api/requests.ts

Available API Testing Tools

Response Expectation Tool

The playwright_expect_response tool allows tests to verify expected HTTP response characteristics before proceeding with further assertions. This tool enables proactive validation of API responses.

Parameters:

Sources: CHANGELOG.md

Response Assertion Tool

The playwright_assert_response tool provides comprehensive response validation capabilities, comparing actual API responses against expected values with detailed error reporting.

Parameters:

Sources: CHANGELOG.md

Custom User Agent Tool

The playwright_custom_user_agent tool enables modification of the User-Agent header for API requests, supporting scenarios requiring specific client identification or browser emulation.

Parameters:

Sources: CHANGELOG.md

Optional Bearer Authorization

API testing tools support optional Bearer token authentication for secured endpoints. This is configured at the request level and follows RFC 6750 specifications.

Configuration:

{
  "url": "https://api.example.com/protected",
  "method": "GET",
  "authorization": {
    "type": "bearer",
    "token": "${API_TOKEN}"
  }
}

Sources: CHANGELOG.md

Request Lifecycle

sequenceDiagram
    participant MCP as MCP Client
    participant API as API Tool Module
    participant LOG as Logging Middleware
    participant HTTP as HTTP Client
    participant EXT as External API
    
    MCP->>API: Tool Call Request
    API->>LOG: Log Tool Start
    LOG->>LOG: Capture Request Context
    API->>API: Validate Parameters
    API->>HTTP: Execute Request
    HTTP->>EXT: HTTP Request
    EXT-->>HTTP: HTTP Response
    HTTP-->>API: Raw Response
    API->>API: Process Response
    API->>API: Run Assertions
    API->>LOG: Log Tool Completion
    LOG-->>API: Log Entry Created
    API-->>MCP: Tool Response

Logging and Monitoring

Request Logging

The logging middleware captures detailed information about API tool executions, following the same pattern used for browser tools. Each API request generates a structured log entry with timing information and sanitized parameter data.

Logging Context Structure:

interface RequestLogContext {
  method: 'TOOL_CALL';
  url: string;
  body?: any;
  statusCode?: number;
  duration?: number;
}

Sources: src/logging/middleware.ts:10-16

Error Handling and Categorization

The logging middleware provides comprehensive error categorization for API-related errors:

Sources: src/logging/middleware.ts:85-120

Sanitization

Sensitive data within API requests is automatically sanitized in logs:

const sensitiveFields = ['password', 'token', 'secret', 'key', 'auth'];
// These fields are replaced with '[REDACTED]' in logs

Sources: src/logging/middleware.ts:180-190

Integration with Browser Tools

The API Testing Tools are designed to work alongside browser automation tools, enabling comprehensive end-to-end testing scenarios:

graph LR
    A[playwright_navigate] --> B[Browser Actions]
    B --> C[Extract Data]
    C --> D[API Validation]
    D --> E[playwright_expect_response]
    E --> F[API Assertions]
    F --> G[playwright_assert_response]
    G --> H[Test Results]

This integration allows for scenarios such as:

1. Data-Driven Testing: Extract test data from the UI using browser tools, then validate against API responses
2. State Verification: Use API tools to verify backend state after browser interactions
3. Hybrid Workflows: Combine UI automation with API validation for complete coverage

Configuration

Environment Variables

Sources: DOCKER.md

Timeout Configuration

API tool timeouts are configurable at the tool call level and can be set per-request:

{
  "timeout": 30000,  // 30 seconds
  "retries": 0       // No automatic retries by default
}

Error Handling Patterns

Tool Response Structure

All API tools return responses following the standard ToolResponse format:

interface ToolResponse {
  content: Array<{
    type: 'text';
    text: string;
  }>;
  isError?: boolean;
}

Sources: src/tools/common/types.ts

Common Error Scenarios

Best Practices

1. Use Assertions Early: Use playwright_expect_response for early failure detection in test suites
2. Sanitize Sensitive Data: Ensure credentials are not logged by using environment variables
3. Set Appropriate Timeouts: Configure timeouts based on expected API response times
4. Combine with Browser Tools: Leverage both API and browser tools for comprehensive testing
5. Monitor Logs: Review logging output for performance analysis and debugging

Related Documentation

• HTTP Mode Example - Running the server in HTTP mode for API testing
• Docker Integration - Containerized deployment for API testing workflows
• Main README - General MCP Playwright server documentation

Related Pages

Related topics: Browser Automation Tools, API Testing Tools

Code Generation and Recording

The Code Generation and Recording system is a module within the MCP Playwright server that enables automatic conversion of MCP tool interactions into executable Playwright test code. This feature captures user actions performed through MCP tools during browser automation sessions and transforms them into structured test cases that can be replayed using Playwright's native test runner.

Overview

The codegen module serves as a bridge between exploratory testing and automated test creation. When developers or AI assistants interact with web applications using MCP Playwright tools (such as playwright_click, playwright_navigate, playwright_fill, etc.), the codegen system records these actions with their parameters and results. Upon session completion, this recorded data can be converted into self-contained Playwright test files.

Sources: src/tools/codegen/index.ts:1-30

Architecture

The codegen system follows a two-phase architecture: Recording and Generation.

graph TD
    A[MCP Tool Execution] --> B[ActionRecorder]
    B --> C[CodegenSession Store]
    C --> D[Session Actions]
    D --> E[PlaywrightGenerator]
    E --> F[Generated Test Code]
    G[CodegenOptions] --> E
    
    style A fill:#e1f5fe
    style F fill:#c8e6c9
    style B fill:#fff3e0
    style E fill:#fff3e0

Core Components

Sources: src/tools/codegen/types.ts:1-35

Data Models

The codegen module defines several TypeScript interfaces that structure the recording and generation process.

CodegenAction

Represents a single recorded action during a codegen session.

export interface CodegenAction {
  toolName: string;
  parameters: Record<string, unknown>;
  timestamp: number;
  result?: unknown;
}

Sources: src/tools/codegen/types.ts:1-10

CodegenSession

Represents an entire recording session containing multiple actions.

export interface CodegenSession {
  id: string;
  actions: CodegenAction[];
  startTime: number;
  endTime?: number;
  options?: CodegenOptions;
}

Sources: src/tools/codegen/types.ts:12-20

CodegenOptions

Configuration options that control code generation behavior.

export interface CodegenOptions {
  outputPath?: string;
  testNamePrefix?: string;
  includeComments?: boolean;
}

Sources: src/tools/codegen/types.ts:26-32

CodegenResult

Output returned after generating test code from a session.

export interface CodegenResult {
  testCode: string;
  filePath: string;
  sessionId: string;
}

Sources: src/tools/codegen/types.ts:34-40

Available Tools

The codegen module exposes the following MCP tools for managing sessions.

start_codegen_session

Initiates a new recording session for capturing MCP tool actions.

export const startCodegenSession: Tool = {
  name: 'start_codegen_session',
  description: 'Start a new code generation session to record MCP tool actions',
  parameters: {
    type: 'object',
    properties: {
      options: {
        type: 'object',
        description: 'Code generation options',
        properties: {
          outputPath: { type: 'string' },
          testNamePrefix: { type: 'string' },
          includeComments: { type: 'boolean' }
        }
      }
    }
  },
  // ...
};

Parameters:

Sources: src/tools/codegen/index.ts:37-58

PlaywrightGenerator Class

The PlaywrightGenerator class handles the transformation of recorded sessions into executable Playwright test code.

Constructor and Configuration

export class PlaywrightGenerator {
  private static readonly DEFAULT_OPTIONS: Required<CodegenOptions> = {
    outputPath: 'tests',
    testNamePrefix: 'MCP',
    includeComments: true,
  };

  private options: Required<CodegenOptions>;

  constructor(options: CodegenOptions = {}) {
    this.validateOptions(options);
    this.options = { ...PlaywrightGenerator.DEFAULT_OPTIONS, ...options };
  }
}

Sources: src/tools/codegen/generator.ts:1-20

Options Validation

The generator performs strict validation on provided options before initializing.

private validateOptions(options: CodegenOptions): void {
  if (options.outputPath && typeof options.outputPath !== 'string') {
    throw new Error('outputPath must be a string');
  }
  if (options.testNamePrefix && typeof options.testNamePrefix !== 'string') {
    throw new Error('testNamePrefix must be a string');
  }
  if (options.includeComments !== undefined && typeof options.includeComments !== 'boolean') {
    throw new Error('includeComments must be a boolean');
  }
}

All options are validated for correct types before being applied, ensuring runtime errors are prevented during test generation.

Sources: src/tools/codegen/generator.ts:22-33

Test Generation Process

async generateTest(session: CodegenSession): Promise<CodegenResult> {
  if (!session || !Array.isArray(session.actions)) {
    throw new Error('Invalid session data');
  }

  const testCase = this.createTestCase(session);
  const testCode = this.generateTestCode(testCase);
  const filePath = this.getOutputFilePath(session);

  return {
    testCode,
    filePath,
    sessionId: session.id,
  };
}

The generation process consists of three steps:

1. Create Test Case - Transforms session actions into a structured PlaywrightTestCase
2. Generate Test Code - Converts the test case into Playwright test syntax
3. Determine Output Path - Resolves the file path based on session ID and configuration

Sources: src/tools/codegen/generator.ts:35-50

Recording Workflow

sequenceDiagram
    participant User
    participant MCP as MCP Server
    participant Recorder as ActionRecorder
    participant Store as CodegenSession Store
    
    User->>MCP: start_codegen_session(options)
    MCP->>Recorder: createSession(options)
    Recorder->>Store: initialize session
    Note over Store: Session ID generated
    
    User->>MCP: playwright_click(selector)
    MCP->>Recorder: record(toolName, args, result)
    Recorder->>Store: append action
    
    User->>MCP: playwright_navigate(url)
    MCP->>Recorder: record(toolName, args, result)
    Recorder->>Store: append action
    
    User->>MCP: stop_codegen_session()
    MCP->>Recorder: finalize session
    Recorder->>Store: set endTime

PlaywrightTestCase Structure

The intermediate representation used during code generation:

export interface PlaywrightTestCase {
  name: string;
  steps: string[];
  imports: Set<string>;
}

Sources: src/tools/codegen/types.ts:22-26

Output Path Resolution

The system uses the workspace root as the base directory for generated tests:

const getWorkspaceRoot = () => {
  return process.cwd();
};

const DEFAULT_OPTIONS: Required<CodegenOptions> = {
  outputPath: path.join(getWorkspaceRoot(), 'e2e'),
  testNamePrefix: 'Test',
  includeComments: true
};

Output paths are handled as follows:

• Absolute paths are used as-is
• Relative paths are resolved from the current working directory

Sources: src/tools/codegen/index.ts:20-30

Integration with MCP Tool Execution

The recording system intercepts MCP tool calls to capture execution data. Each recorded action preserves:

• The exact tool name (e.g., playwright_click, playwright_fill)
• All parameters passed to the tool
• The timestamp of execution
• Optional result data from the tool

This captured data enables precise reproduction of user interactions when the generated test is executed.

Error Handling

The generator validates input at initialization and during generation:

Sources: src/tools/codegen/generator.ts:22-33

Usage Example

# Start a recording session with custom options
npx @executeautomation/playwright-mcp-server

# Within your MCP client, call:
# start_codegen_session with options { outputPath: "./tests", testNamePrefix: "E2E" }

# Perform actions using playwright_* tools
# playwright_navigate, playwright_click, etc. are recorded

# Generate test code from the session

The generated test code can then be executed with:

npx playwright test ./tests/generated-test.spec.ts

Related Documentation

• README.md - Main project documentation
• CHANGELOG.md - Version history for codegen features
• examples/http-mode-example.md - HTTP mode integration

Related Pages

Related topics: Getting Started, Configuration Guide

Docker Deployment

Overview

The Playwright MCP Server provides Docker containerization support, enabling isolated execution environments for browser automation tasks. Docker deployment offers consistent runtime across different systems, simplified dependency management, and easy distribution of the MCP server.

The containerized solution is designed to work with pre-built artifacts from a local build, ensuring minimal image size while maintaining full functionality for browser automation through the MCP protocol.

Sources: DOCKER.md

Architecture

graph TD
    subgraph "Host System"
        A[Local Build Directory] -->|npm install --omit=dev| B[node_modules]
        A -->|npm run build| C[dist/]
    end
    
    subgraph "Docker Container"
        D[Dockerfile] -->|COPY| E[mcp-playwright:latest]
        B -->|Production deps| E
        C -->|Built artifacts| E
    end
    
    subgraph "Runtime Components"
        E -->|stdin/stdout| F[MCP Client]
        E -->|Browser Automation| G[Playwright Browsers]
    end
    
    F -->|JSON-RPC| H[Claude Desktop / VS Code / Custom Client]

Prerequisites

Sources: DOCKER.md:prerequisites-section

Building the Docker Image

Standard Build Process

The Dockerfile copies node_modules and dist from the local build directory directly into the image. This approach requires building artifacts locally before containerization.

# 1. Install production dependencies only
npm install --omit=dev

# 2. Build the project
npm run build

# 3. Build the Docker image
docker build -t mcp-playwright:latest .

Automated Build Script

A convenience script is provided for the build process:

chmod +x docker-build.sh
./docker-build.sh

Sources: DOCKER.md:building-docker-image-section

Build with Custom Tag

docker build -t mcp-playwright:1.0.6 .

Building from Source Inside Docker

For environments where you prefer building inside the container:

FROM node:20-alpine AS builder

WORKDIR /app
COPY package*.json ./
ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
RUN npm ci

COPY src ./src
COPY tsconfig.json ./
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --only=production
CMD ["node", "dist/index.js"]

Sources: DOCKER.md:building-from-source-section

Running the Server

Interactive Mode (Recommended for MCP)

MCP servers communicate via stdin/stdout, requiring interactive mode for proper operation:

docker run -i --rm mcp-playwright:latest

Sources: DOCKER.md:running-the-server-section

Using Docker Compose

# Start the server
docker compose run --rm playwright-mcp

# Or build and run
docker compose build
docker compose run --rm playwright-mcp

The provided docker-compose.yml:

services:
  playwright-mcp:
    build:
      context: .
      dockerfile: Dockerfile
    image: mcp-playwright:latest
    container_name: playwright-mcp-server
    stdin_open: true
    tty: true
    environment:
      - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1

Sources: docker-compose.yml

MCP Client Integration

Claude Desktop Configuration

Update the Claude Desktop configuration file:

{
  "mcpServers": {
    "playwright-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
    }
  }
}

Sources: DOCKER.md:claude-desktop-configuration-section

VS Code MCP Extension

{
  "mcpServers": {
    "playwright-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
    }
  }
}

Sources: DOCKER.md:vs-code-mcp-extension-section

Configuration Options

Environment Variables

#### Using Environment Variables in Docker

docker run -i --rm \
  -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
  mcp-playwright:latest

#### Using Environment Variables in Docker Compose

services:
  playwright-mcp:
    environment:
      - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
      - NODE_ENV=production

Sources: DOCKER.md:environment-variables-section

Volume Mounts

For persistent data or file sharing with the container:

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  mcp-playwright:latest

services:
  playwright-mcp:
    volumes:
      - ./data:/app/data
      - ./screenshots:/app/screenshots

Sources: DOCKER.md:volume-mounts-section

Resource Limits

docker run -i --rm \
  --cpus="2.0" \
  --memory="2g" \
  mcp-playwright:latest

services:
  playwright-mcp:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G

Sources: DOCKER.md:resource-limits-section

Custom Network Configuration

# Create custom network
docker network create mcp-network

# Run container on custom network
docker run -i --rm --network mcp-network mcp-playwright:latest

Sources: DOCKER.md:advanced-usage-section

Troubleshooting

Container Exits Immediately

MCP servers wait for input on stdin. Ensure the -i flag is used:

docker run -i --rm mcp-playwright:latest

Sources: DOCKER.md:troubleshooting-section

Browser Not Found

The Docker image skips browser downloads by default to reduce size. Playwright downloads browsers on first use. To pre-install browsers:

FROM mcp-playwright:latest

# Install Playwright browsers
RUN npx playwright install chromium --with-deps

Sources: DOCKER.md:browser-not-found-section

Permission Issues

If encountering permission issues with mounted volumes:

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  --user $(id -u):$(id -g) \
  mcp-playwright:latest

Sources: DOCKER.md:permission-issues-section

Health Checks

Add a health check to your docker-compose.yml:

services:
  playwright-mcp:
    healthcheck:
      test: ["CMD", "node", "-e", "process.exit(0)"]
      interval: 30s
      timeout: 10s
      retries: 3

Sources: DOCKER.md:health-checks-section

Security Considerations

Run as Non-root User (Recommended)

FROM mcp-playwright:latest
USER node

Read-only Root Filesystem

docker run -i --rm --read-only mcp-playwright:latest

Vulnerability Scanning

docker scan mcp-playwright:latest

Sources: DOCKER.md:security-considerations-section

Image Optimization

Current image size: ~200MB (without browsers)

Sources: DOCKER.md:image-size-optimization-section

Workflow Summary

graph LR
    A[Local Build] -->|npm install --omit=dev| B[Dependencies]
    A -->|npm run build| C[dist/]
    B -->|COPY| D[Docker Build]
    C -->|COPY| D
    D -->|docker build| E[Image Created]
    E -->|Interactive Mode| F[MCP Server Running]
    F -->|JSON-RPC| G[MCP Client Connected]

Quick Reference

Related Pages

Related topics: Getting Started, Transport Modes, Docker Deployment

Configuration Guide

This guide covers all configuration options for the mcp-playwright MCP server, including stdio mode, HTTP server mode, Docker deployment, and integration with AI assistants like Claude Desktop.

Overview

The mcp-playwright server provides browser automation capabilities through the Model Context Protocol (MCP). It supports multiple transport modes and can be configured to work with different MCP clients. Sources: package.json:1-50

graph TD
    A[MCP Client] --> B{Mode Selection}
    B --> C[Stdio Mode]
    B --> D[HTTP Mode]
    B --> E[Docker Mode]
    C --> F[stdin/stdout]
    D --> G[localhost:8931]
    E --> H[Docker Container]
    F --> I[Playwright Browser]
    G --> I
    H --> I

Stdio Mode Configuration

Stdio mode is the primary transport mechanism for MCP communication, using standard input/output streams. This mode is automatically selected when running via npx or direct node execution. Sources: README.md:1-30

Claude Desktop Configuration

For Claude Desktop integration, add the server configuration to your Claude Desktop config file:

Configuration schema:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

VS Code MCP Extension

For VS Code with MCP extension:

{
  "name": "playwright",
  "command": "npx",
  "args": ["-y", "@executeautomation/playwright-mcp-server"]
}

Note: In stdio mode, logging is automatically directed to files only (not console) to maintain clean JSON-RPC communication. Logs are written to ~/playwright-mcp-server.log. Sources: README.md:25-27

HTTP Mode Configuration

HTTP mode enables the MCP server to run as a standalone HTTP server, useful for remote deployments or IDE integrations that support HTTP transport. Sources: src/http-server.ts:1-50

Starting the HTTP Server

# Using npx
npx @executeautomation/playwright-mcp-server --port 8931

# Or after global installation
npm install -g @executeautomation/playwright-mcp-server
playwright-mcp-server --port 8931

HTTP Server Endpoints

Security Configuration

The HTTP server binds to 127.0.0.1 (localhost only) by default to prevent external network access. Sources: src/http-server.ts:35-36

const host = '127.0.0.1';
const httpServer = app.listen(port, host, () => {
  logger.info(`Playwright MCP HTTP server listening on ${host}:${port}`);
});

Claude Desktop HTTP Configuration

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Health Check

curl http://localhost:8931/health

Response format:

{
  "status": "ok",
  "version": "1.0.10",
  "activeSessions": 0
}

Docker Configuration

The Docker image provides a containerized deployment option for the mcp-playwright server. Sources: DOCKER.md:1-50

Basic Docker Run

docker run -i --rm mcp-playwright:latest

Docker Compose Configuration

services:
  playwright-mcp:
    image: mcp-playwright:latest

Claude Desktop Docker Configuration

{
  "mcpServers": {
    "playwright-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
    }
  }
}

VS Code Docker Configuration

{
  "name": "playwright-docker",
  "command": "docker",
  "args": ["run", "-i", "--rm", "mcp-playwright:latest"]
}

Environment Variables

Configure server behavior using environment variables. Sources: DOCKER.md:20-35

Available Environment Variables

Docker Environment Variable Examples

Via docker run:

docker run -i --rm \
  -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \
  -e NODE_ENV=production \
  mcp-playwright:latest

Via docker-compose.yml:

services:
  playwright-mcp:
    environment:
      - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
      - NODE_ENV=production

Volume Mounts

Share files and persist data between the host and container. Sources: DOCKER.md:36-50

Docker Volume Examples

Via docker run:

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/screenshots:/app/screenshots \
  mcp-playwright:latest

Via docker-compose.yml:

services:
  playwright-mcp:
    volumes:
      - ./data:/app/data
      - ./screenshots:/app/screenshots

User and Permissions

Handle permission issues with mounted volumes by specifying user:

docker run -i --rm \
  -v $(pwd)/data:/app/data \
  --user $(id -u):$(id -g) \
  mcp-playwright:latest

Resource Limits

Configure CPU and memory constraints for containerized deployments. Sources: DOCKER.md:85-100

Docker Resource Limits

services:
  playwright-mcp:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G

Via docker run:

docker run -i --rm \
  --cpus="2.0" \
  --memory="2g" \
  mcp-playwright:latest

Network Configuration

Custom Network

docker network create mcp-network
docker run -i --rm --network mcp-network mcp-playwright:latest

Security Considerations

Health Checks

Add health check configuration to docker-compose.yml:

services:
  playwright-mcp:
    healthcheck:
      test: ["CMD", "node", "-e", "process.exit(0)"]
      interval: 30s
      timeout: 10s
      retries: 3

Troubleshooting Configuration Issues

Container Exits Immediately

MCP servers wait for input on stdin. Ensure the -i flag is used:

docker run -i --rm mcp-playwright:latest

Browser Not Found

The Docker image skips browser downloads by default. To pre-install browsers, create a custom Dockerfile:

FROM mcp-playwright:latest
RUN npx playwright install chromium --with-deps

Tool Name Length Constraints

When adding new tools, consider the combined server and tool name length. Some clients like Cursor have a 60-character limit for server_name:tool_name. Sources: README.md:10-15

Current server name: playwright-mcp

Ensure tool names are short enough to not exceed this limit when combined.

Image Specifications

Building Custom Docker Images

Optimized Build (Recommended)

Uses pre-built artifacts from local development:

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY node_modules ./node_modules
COPY dist ./dist
CMD ["node", "dist/index.js"]

Full Build from Source

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
RUN npm ci

COPY src ./src
COPY tsconfig.json ./
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --only=production
CMD ["node", "dist/index.js"]

Dependencies Configuration

The package.json defines core dependencies for the MCP server. Sources: package.json:10-35

Runtime Dependencies

Development Dependencies

Logging Configuration

In stdio mode, logs are automatically directed to files to maintain clean JSON-RPC communication. Sources: README.md:27

Log file location: ~/playwright-mcp-server.log

The logging middleware captures:

• Request IDs for traceability
• Tool execution timing and results
• Error categorization (validation, system, resource, authentication, rate_limit)
• Sanitized request bodies (sensitive fields redacted)

Summary

Doramagic Pitfall Log

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

1. Installation risk: Playwright is asking for an specific browser version.

• Severity: high
• Finding: Installation risk is backed by a source signal: Playwright is asking for an specific browser version.. 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/executeautomation/mcp-playwright/issues/117

2. Security or permission risk: How to configure proxy and storageState when launching browser in Playwright MCP?

• Severity: high
• Finding: Security or permission risk is backed by a source signal: How to configure proxy and storageState when launching browser in Playwright MCP?. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• 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/executeautomation/mcp-playwright/issues/203

3. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. 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: capability.host_targets | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | host_targets=mcp_host, claude, cursor

4. Configuration risk: Add Clarvia AEO score badge to README (AEO 32/100)

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Add Clarvia AEO score badge to README (AEO 32/100). 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/executeautomation/mcp-playwright/issues/212

5. Configuration risk: Add policy enforcement for browser automation and HTTP request tools

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Add policy enforcement for browser automation and HTTP request tools. 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/executeautomation/mcp-playwright/issues/216

6. 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:898077246 | https://github.com/executeautomation/mcp-playwright | README/documentation is current enough for a first validation pass.

7. Project risk: How to pass in the `--ignore-https-errors` parameter?

• Severity: medium
• Finding: Project risk is backed by a source signal: How to pass in the --ignore-https-errors parameter?. 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/executeautomation/mcp-playwright/issues/202

8. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | last_activity_observed missing

9. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium

10. Security or permission risk: No sandbox install has been executed yet; downstream must verify before user use.

• Severity: medium
• Finding: No sandbox install has been executed yet; downstream must verify before user use.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.safety_notes | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | No sandbox install has been executed yet; downstream must verify before user use.

11. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:898077246 | https://github.com/executeautomation/mcp-playwright | no_demo; severity=medium

12. Security or permission risk: Feature Request: Add browser context persistence for login state (userDataDir/storageState)

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: Feature Request: Add browser context persistence for login state (userDataDir/storageState). Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• 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/executeautomation/mcp-playwright/issues/201

Community Discussion Evidence

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

• Add policy enforcement for browser automation and HTTP request tools - github / github_issue
• Add Clarvia AEO score badge to README (AEO 32/100) - github / github_issue
• Free MCP security scan report for @executeautomation/playwright-mcp-serv - github / github_issue
• How to configure proxy and storageState when launching browser in Playwr - github / github_issue
• Security Advisory: SSRF, Prompt Injection, and Arbitrary JavaScript Exec - github / github_issue
• Playwright is asking for an specific browser version. - github / github_issue
• How to pass in the --ignore-https-errors parameter? - github / github_issue
• Feature Request: Add browser context persistence for login state (userDa - github / github_issue
• Configuration risk needs validation - GitHub / issue