Playwright MCP Server v6
Intelligent Playwright + MCP + BDD Automation Framework Generator
A production-ready Java-based Model Context Protocol (MCP) server that bridges LLMs with a live Chromium browser using Playwright Java.
This framework records real browser interactions, analyzes user intent, generates maintainable BDD automation frameworks, supports intelligent playback with recovery, and exposes atomic browser tools for AI agents.
Table of Contents
- Overview
- Key Features
- Architecture
- Core Components
- Technology Stack
- Prerequisites
- Installation & Setup
- MCP Integration
- Exposed MCP Tools
- Smart Wait Engine
- Intent Analysis Engine
- Intelligent BDD Generation
- Generated Framework Structure
- UiActions Abstraction Layer
- Locator Strategy
- Parallel Playback Support
- Failure Recovery System
- Supported Browser Actions
- Environment Variables
- Build & Run
- Example Workflow
- Sample Recording JSON
- Troubleshooting Guide
- Performance & Design Decisions
- Security Considerations
- Future Enhancements
- Best Practices
- FAQ
- License
Overview
Playwright MCP Server is an intelligent automation orchestration layer that enables Large Language Models (LLMs) to:
- Launch and control browsers
- Record user interactions
- Replay workflows reliably
- Generate enterprise-grade BDD frameworks
- Execute atomic browser operations
- Analyze raw browser events into business intents
- Create reusable Page Object Models automatically
The framework is optimized for:
- AI-assisted QA automation
- Self-healing browser interactions
- Intent-driven BDD generation
- Framework-agnostic automation design
- Parallel execution
- Enterprise automation scalability
Key Features
Browser Recording Engine
- Records clicks, fills, navigations, key presses, uploads, dropdowns, and scrolls
- Captures semantic locators automatically
- Supports headed and headless execution
- CSP bypass support
- Smart event de-duplication
- Session-based recording management
Smart Wait Engine (v6)
Automatic synchronization before and after every action:
- DOM ready checks
- Network idle detection
- Element visibility validation
- Enabled-state verification
- DOM stabilization logic
- Action-aware waits
Intent Analyzer
Converts raw DOM events into business-level intents:
Intelligent BDD Generator
Automatically generates:
- Feature files
- Step definitions
- Page Objects
- Runner classes
- UiActions abstraction layer
- Playwright implementation layer
- Scenario Outlines
- Data-driven examples
Parallel Playback Engine
- ThreadLocal Playwright sessions
- Multi-threaded replay
- Chunk-based event distribution
- Isolated browser contexts
- Concurrent execution support
Recovery & Failure Handling
- Screenshot capture on failure
- HTML dump generation
- Automatic DOM re-sync
- URL validation
- Retry engine
- Smart recovery handling
Framework Abstraction Layer
Generated frameworks use:
ui.click(locator);
ui.fill(locator, value);
ui.navigate(url);
This enables future migration to:
- Selenium
- Cypress
- WebDriverIO
- Appium
- Any UI engine
without changing Page Objects.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ MCP HOST / LLM │
│ Claude / Cursor / Cline / Custom AI Agent │
└──────────────────────┬──────────────────────────────────────┘
│
JSON-RPC over stdio
│
┌──────────────────────▼──────────────────────────────────────┐
│ Playwright MCP Server │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ MCP Tool Layer │ │
│ │ │ │
│ │ start_recording │ │
│ │ stop_recording │ │
│ │ playback_recording │ │
│ │ generate_playwright_bdd │ │
│ │ execute_atomic_action │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Intent Analysis Engine │ │
│ │ │ │
│ │ LOGIN │ │
│ │ SEARCH │ │
│ │ FORM_SUBMIT │ │
│ │ TRANSFER │ │
│ │ RAW_ACTION │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Smart Wait Engine │ │
│ │ │ │
│ │ DOM Ready │ │
│ │ Network Idle │ │
│ │ Element Visibility │ │
│ │ Enabled State │ │
│ │ DOM Stabilization │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ BDD Code Generator │ │
│ │ │ │
│ │ Feature Files │ │
│ │ Step Definitions │ │
│ │ Page Objects │ │
│ │ Runners │ │
│ │ UiActions │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────────────┐
│ Playwright Java │
│ Chromium Browser │
└─────────────────────────────────────────────────────────────┘
Core Components
1. PlaywrightMcpServer.java
Main orchestration engine responsible for:
- MCP tool registration
- Browser lifecycle management
- Event recording
- Playback execution
- Smart waits
- Retry handling
- Parallel execution
- Failure recovery
- Session management
2. IntentAnalyzer.java
Transforms low-level browser events into meaningful business actions.
Supported Intent Types
3. BddCodeGenerator.java
Generates complete automation frameworks.
Generated Artifacts
- Feature files
- Step definitions
- Page Objects
- Runner classes
- UiActions interface
- Playwright implementation
- Data-driven scenarios
- Assertions
- Utility methods
Technology Stack
Prerequisites
Installation & Setup
1. Clone Repository
git clone <repository-url>
cd playwright-mcp-server
2. Build Project
mvn clean package -DskipTests
3. Install Playwright Browsers
mvn exec:java@install-browsers
4. Verify Build
Generated JAR:
target/playwright-mcp-server.jar
MCP Integration
Claude Desktop Configuration
macOS
~/Library/Application Support/Claude/claude_desktop_config.json
Windows
%APPDATA%\Claude\claude_desktop_config.json
Example Configuration
{
"mcpServers": {
"playwright": {
"command": "java",
"args": [
"-jar",
"/absolute/path/to/playwright-mcp-server.jar"
]
}
}
}
Restart Claude Desktop after configuration.
Exposed MCP Tools
1. start_recording
Launches Chromium and starts interaction recording.
Input
{
"url": "https://example.com",
"sessionName": "Login Flow",
"headless": false
}
Features
- CSP bypass
- JS injection
- Browser lifecycle management
- Event queue setup
- Session metadata generation
2. stop_recording
Stops recording and returns structured JSON.
Input
{}
Output
- Raw browser events
- Structured intents
- Session metadata
- Timing data
- Recording statistics
3. playback_recording
Replays recorded events intelligently.
Input
{
"jsonRecording": "...",
"headless": true,
"parallel": false,
"threads": 1
}
Features
- Smart waits
- Retry engine
- Recovery logic
- Parallel execution
- Failure artifact generation
4. generate_playwright_bdd
Generates complete BDD automation framework.
Input
{
"jsonRecording": "...",
"featureName": "User Login",
"framework": "cucumber",
"tags": "@smoke @regression"
}
Supported Frameworks
Generated Files
5. execute_atomic_action
Executes single Playwright actions.
Example
{
"action": "fill",
"selector": "placeholder:Search",
"value": "Playwright"
}
Supported Actions
Smart Wait Engine
The Smart Wait Engine automatically stabilizes browser state.
Wait Strategy
Benefits
- Reduces flaky tests
- Removes hard-coded waits
- Stabilizes asynchronous pages
- Improves replay reliability
Intent Analysis Engine
The Intent Analyzer converts low-level browser actions into business workflows.
Example
Raw Events
FILL username
FILL password
CLICK login
Generated Intent
LOGIN(username, password)
Generated Gherkin
When user logs in with "john" and "<password>"
Intelligent BDD Generation
The generator creates enterprise-ready automation frameworks.
Generated Feature Example
@smoke @regression
Feature: User Login
Background:
Given the browser is open
Scenario: User Login
When user logs in with "john" and "<password>"
Generated Page Object Example
public class LoginPage {
private final UiActions ui;
private final String USERNAME_FIELD = "#username";
private final String PASSWORD_FIELD = "#password";
public LoginPage login(String username, String password) {
ui.fill(USERNAME_FIELD, username);
ui.fill(PASSWORD_FIELD, password);
return this;
}
}
Generated Framework Structure
generated-project/
│
├── pom.xml
│
├── src/
│ ├── main/
│ │ └── java/com/qa/
│ │ ├── actions/
│ │ │ ├── UiActions.java
│ │ │ └── PlaywrightUiActions.java
│ │ │
│ │ └── pages/
│ │ └── UserLoginPage.java
│ │
│ └── test/
│ ├── java/com/qa/
│ │ ├── runners/
│ │ │ └── UserLoginRunner.java
│ │ │
│ │ └── stepdefs/
│ │ └── UserLoginSteps.java
│ │
│ └── resources/
│ ├── features/
│ │ └── UserLogin.feature
│ │
│ └── TestData/
│ └── testdata.properties
UiActions Abstraction Layer
Purpose
Decouples Page Objects from Playwright.
Benefits
- Framework independence
- Easy migration
- Cleaner architecture
- Better maintainability
- Improved scalability
Example
public interface UiActions {
void click(String selector);
void fill(String selector, String value);
void navigate(String url);
}
Locator Strategy
The framework prioritizes resilient semantic locators.
Priority Order
Examples
role:button:Login
placeholder:Search
label:Email
testid:submit-btn
Parallel Playback Support
Features
- Multi-threaded execution
- Thread-isolated browser sessions
- Chunk-based replay
- ThreadLocal Playwright instances
Example
{
"parallel": true,
"threads": 4
}
Failure Recovery System
On action failure the framework:
- Captures screenshot
- Dumps HTML
- Logs failure details
- Validates URL
- Attempts DOM re-sync
- Continues execution where possible
Failure Artifact Directory
./mcp-failures/
Generated artifacts:
failure.png
failure.html
failure.log
Environment Variables
Build & Run
Package Project
mvn clean package
Run Server
java -jar target/playwright-mcp-server.jar
Run Generated Framework
mvn test
Run Specific Tags
mvn test -Dcucumber.filter.tags="@smoke"
Example Workflow
Step 1 — Start Recording
{
"url": "https://example.com"
}
Step 2 — Perform Browser Actions
- Login
- Search
- Submit forms
- Upload files
Step 3 — Stop Recording
{}
Step 4 — Generate Framework
{
"featureName": "User Login"
}
Step 5 — Execute Tests
mvn test
Sample Recording JSON
{
"schemaVersion": "6.0.0",
"sessionName": "Login Test",
"status": "COMPLETED",
"events": [
{
"actionType": "FILL",
"selector": "#username",
"inputValue": "john"
},
{
"actionType": "CLICK",
"selector": "#login"
}
],
"intents": [
{
"intentType": "LOGIN",
"description": "User login"
}
]
}
Troubleshooting Guide
Browser Installation
mvn exec:java@install-browsers
Debug Logging
export MCP_LOG_LEVEL=DEBUG
Performance & Design Decisions
Security Considerations
- CSP bypass is enabled intentionally for automation recording
- Sensitive passwords are masked during intent generation
- Browser contexts are isolated
- Failure artifacts may contain sensitive information
- Generated frameworks should not commit secrets
Future Enhancements
Planned improvements:
- Selenium UiActions implementation
- Firefox and WebKit support
- AI-powered self-healing selectors
- Visual validation engine
- API testing integration
- Test impact analysis
- Cloud execution support
- Docker support
- Kubernetes scaling
- CI/CD templates
- Reporting dashboard
Best Practices
Recommended
- Use semantic locators
- Prefer role/testid selectors
- Keep generated frameworks version controlled
- Store secrets externally
- Run parallel execution carefully
- Use Scenario Outlines for test data
Avoid
- Hard-coded waits
- Absolute XPath selectors
- Sharing browser contexts across threads
- Storing credentials in source code
FAQ
Does this support headless execution?
Yes.
Can generated frameworks run independently?
Yes. Generated projects are standalone Maven automation frameworks.
Does this support parallel execution?
Yes.
Can Selenium be plugged in later?
Yes. The UiActions abstraction was specifically designed for this.
Does the framework support retries?
Yes. Playback includes retry and recovery logic.
Can I generate data-driven frameworks?
Yes. Scenario Outline generation is supported.
License
This project is intended for educational, enterprise automation, and AI-assisted testing use cases.
Please add your preferred license:
- MIT
- Apache 2.0
- Proprietary Enterprise License
Final Notes
Playwright MCP Server v6 is designed as an AI-native automation framework generation platform.
It combines:
- Playwright browser automation
- MCP protocol tooling
- Intent analysis
- Smart synchronization
- Enterprise BDD generation
- Parallel execution
- Recovery-aware replay
into a single extensible architecture.
The result is a scalable foundation for AI-assisted QA automation systems, autonomous browser agents, and intelligent framework generation pipelines.
