MCP Playwright Server

A comprehensive Model Context Protocol (MCP) server for browser automation using Playwright. This server enables AI assistants to control browsers via the MCP protocol, providing powerful tools for web testing, accessibility audits, and browser automation.

Features

• 🌐 Multi-Browser Support - Chromium, Firefox, and WebKit
• 🔧 50+ Browser Automation Tools - Navigation, interaction, assertions, screenshots
• ♿ Accessibility Testing - Built-in axe-core integration with WCAG compliance checks
• 🔒 Session Management - Isolated browser contexts with rate limiting
• 📸 Visual Testing - Screenshots, video recording, and tracing
• 🧪 AI Test Agents - Automated test planning, generation, and healing

Technology Stack

Category	Technologies
Runtime	Node.js 18+
Language	TypeScript 5.8
Browser Automation	Playwright 1.52+
Protocol	Model Context Protocol (MCP) SDK
Validation	Zod
Accessibility	@axe-core/playwright
Logging	Winston
Testing	@playwright/test
Linting	ESLint 9, Prettier

Architecture

AI Client → MCP Protocol → Tool Handler → BrowserManager → Action Module → Playwright API
                                ↑
                         SessionManager (lifecycle, rate limiting)

Layer Responsibilities

Layer	Location	Purpose
Entry	src/index.ts	Bootstrap, graceful shutdown
MCP Server	src/server/mcp-server.ts	Tool/resource registration, session cleanup
Handlers	src/server/handlers/	Tool definitions grouped by category
Browser Manager	src/playwright/browser-manager.ts	Orchestrates action modules
Actions	src/playwright/actions/	Domain-specific Playwright operations
Session Manager	src/playwright/session-manager.ts	Session/page lifecycle, rate limiting

Getting Started

Prerequisites

• Node.js 18 or higher
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/j0hanz/playwright-mcp.git
cd playwright-mcp

# Install dependencies
npm install

# Install Playwright browsers
npm run install:browsers

Configuration

Create a .env file in the project root (optional):

LOG_LEVEL=info              # debug, info, warn, error
DEFAULT_BROWSER=chromium    # chromium, firefox, webkit
HEADLESS=true               # Run headless mode
MAX_SESSIONS=5              # Concurrent sessions (1-20)
SESSION_TIMEOUT=1800000     # Session expiry in ms (30 min)
TIMEOUT_ACTION=20000        # Element action timeout in ms
TIMEOUT_NAVIGATION=30000    # Page navigation timeout in ms

Running the Server

# Development mode (with hot reload)
npm run dev

# Production build and run
npm run build
npm start

Project Structure

├── src/
│   ├── index.ts                    # Application entry point
│   ├── config/
│   │   ├── server-config.ts        # Environment configuration
│   │   └── types.ts                # TypeScript type definitions
│   ├── server/
│   │   ├── mcp-server.ts           # MCP server implementation
│   │   └── handlers/               # Tool handler categories
│   │       ├── browser-tools.ts    # Browser lifecycle tools
│   │       ├── navigation-tools.ts # Navigation tools
│   │       ├── interaction-tools.ts# Click, fill, hover tools
│   │       ├── assertion-tools.ts  # Web-first assertions
│   │       ├── page-tools.ts       # Screenshots, content, a11y
│   │       ├── test-tools.ts       # Test file management
│   │       ├── advanced-tools.ts   # Network, tracing, dialogs
│   │       └── schemas.ts          # Zod validation schemas
│   ├── playwright/
│   │   ├── browser-manager.ts      # Central browser orchestration
│   │   ├── session-manager.ts      # Session lifecycle
│   │   ├── browser-launcher.ts     # Browser launch logic
│   │   └── actions/                # Domain-specific actions
│   │       ├── assertion-actions.ts
│   │       ├── interaction-actions.ts
│   │       ├── navigation-actions.ts
│   │       └── ...
│   └── utils/
│       ├── error-handler.ts        # Centralized error handling
│       └── logger.ts               # Winston logger
├── tests/                          # Playwright test files
├── specs/                          # Human-readable test plans
├── .github/
│   ├── agents/                     # AI agent definitions
│   ├── prompts/                    # Agent prompts
│   └── copilot-instructions.md     # Development guidelines
└── playwright.config.ts            # Playwright test configuration

Available Tools

Browser Lifecycle

Tool	Description
browser_launch	Launch browser (Chromium, Firefox, WebKit) with optional auth state
browser_close	Close browser session
browser_tabs	List, create, close, or select browser tabs
sessions_list	List all active browser sessions
save_storage_state	Save cookies/localStorage for auth reuse
session_reset_state	Clear session data for test isolation

Navigation

Tool	Description
browser_navigate	Navigate to URL
browser_history	Go back/forward in history
browser_reload	Reload current page
handle_dialog	Accept/dismiss browser dialogs

Interaction

Tool	Description
element_click	Click by role, text, testid, or selector
element_fill	Fill inputs by label, placeholder, or selector
element_hover	Hover over elements
select_option	Select dropdown options
keyboard_press	Press keys (Enter, Tab, shortcuts)
keyboard_type	Type text character by character
checkbox_set	Check/uncheck checkboxes
file_upload	Upload files
drag_and_drop	Drag and drop elements

Assertions

Tool	Description
assert_element	Assert state (visible, hidden, enabled, disabled)
assert_text	Assert element text content
assert_value	Assert input value
assert_url	Assert page URL
assert_title	Assert page title
assert_attribute	Assert element attribute
assert_css	Assert CSS property
assert_checked	Assert checkbox state
assert_count	Assert element count

Page Operations

Tool	Description
page_screenshot	Capture screenshots (full page, element, region)
page_pdf	Generate PDF from page (Chromium only)
page_content	Get HTML and text content
page_evaluate	Execute JavaScript (read-only)
wait_for_selector	Wait for elements
page_wait_for_load_state	Wait for page load
accessibility_scan	Run axe-core accessibility audit
browser_snapshot	Get accessibility tree snapshot

Cookie Management

Tool	Description
cookies_get	Retrieve cookies from browser context
cookies_set	Add cookies (auth tokens, sessions)
cookies_clear	Clear all or specific cookies

Advanced

Tool	Description
network_mock	Mock network responses
network_unroute	Remove network mocks
tracing_start / tracing_stop	Record execution traces
console_capture	Capture console messages
har_record_start	Record HTTP archive
clock_install	Control time in tests
video_path	Get video recording path

Best Practices for Stable Tests

Following these practices will ensure your tests are resilient, maintainable, and less prone to flakiness. See the full Best Practices Guide for detailed examples.

Core Principles

1. Use Semantic, User-Facing Locators

   • Role-based locators are most reliable: getByRole('button', { name: 'Submit' })
   • Avoid CSS selectors and XPath — these break when styling changes
   • Priority: Role → Label → Placeholder → Text → TestId → CSS (last resort)

2. Use Locator Chaining and Filtering

   • Chain locators to narrow searches: page.getByRole('listitem').filter({ hasText: 'Product 2' })
   • Filter by text or other locators for dynamic content
   • This reduces strict mode violations and increases clarity

3. Always Use Web-First Assertions

   • Use expect() assertions which auto-wait: await expect(page.getByText('Success')).toBeVisible()
   • Don't use direct checks like isVisible() without expect
   • Assertions wait up to 5 seconds (configurable) before failing

4. Avoid Common Pitfalls

   • ❌ waitForTimeout() — use specific waits instead
   • ❌ waitForLoadState('networkidle') — use 'domcontentloaded' or wait for elements
   • ❌ CSS class selectors — use role/label/text locators
   • ❌ Screenshots as selectors — use browser_snapshot for finding elements
   • ❌ test.only() or test.skip() — remove before committing

Example: Good Test Structure

test('Add todo and verify', async ({ page }) => {
  // Navigate
  await page.goto('/');

  // Get accessibility snapshot to understand page structure
  const snapshot = await page.accessibility.snapshot();

  // Interact using semantic locators (role > label > text)
  await page.getByPlaceholder('What needs to be done?').fill('Buy groceries');
  await page.getByRole('button', { name: 'Add' }).click();

  // Verify using web-first assertions (auto-wait)
  await expect(page.getByText('Buy groceries')).toBeVisible();
  await expect(page.getByRole('listitem')).toHaveCount(1);
});

Locator Priority

When interacting with elements, prefer user-facing locators (most reliable first):

1. Role ⭐ - element_click(locatorType: 'role', role: 'button', name: 'Submit')
2. Label ⭐ - element_fill(locatorType: 'label', value: 'Email', text: '...')
3. Text - element_click(locatorType: 'text', value: 'Learn more')
4. Placeholder - element_fill(locatorType: 'placeholder', value: 'Search...')
5. TestId - element_click(locatorType: 'testid', value: 'submit-btn')
6. Selector - CSS selector (last resort only)

Development Workflow

# Watch mode with hot reload
npm run dev

# Build TypeScript to dist/
npm run build

# Run ESLint
npm run lint
npm run lint:fix

# Type check without emit
npm run type-check

# Format with Prettier
npm run format

# Run tests
npm test
npm run test:ui      # Interactive UI
npm run test:headed  # Visible browser
npm run test:debug   # Debug mode

Before committing: Run npm run lint && npm run type-check && npm run build

Coding Standards

Tool Registration Pattern

server.registerTool(
  'tool_name',
  {
    title: 'Human Title',
    description: 'What this tool does',
    inputSchema: {
      /* Zod schemas */
    },
    outputSchema: {
      /* Result shape */
    },
  },
  createToolHandler(async (input) => {
    const result = await browserManager.someMethod(input);
    return {
      content: [{ type: 'text', text: 'Human readable' }],
      structuredContent: result, // Machine readable
    };
  }, 'Error prefix message')
);

Action Module Pattern

export class MyActions extends BaseAction {
  async myOperation(sessionId: string, pageId: string, options: Options) {
    return this.executePageOperation(
      sessionId,
      pageId,
      'My operation',
      async (page) => {
        // Playwright operations
        return { success: true, data: '...' };
      }
    );
  }
}

Error Handling

import {
  ErrorCode,
  ErrorHandler,
  validateUUID,
} from '../utils/error-handler.js';

validateUUID(sessionId, 'sessionId'); // Throws on invalid
throw ErrorHandler.sessionNotFound(id); // Factory methods
throw ErrorHandler.handlePlaywrightError(e); // Maps Playwright errors

Testing

Tests use @playwright/test framework. Configuration is in playwright.config.ts.

npm test                 # Run all tests
npm run test:ui          # Interactive test UI
npm run test:headed      # With visible browser
npm run test:debug       # Debug mode with inspector
npm run test:trace       # Record traces
npm run test:report      # Show HTML report

Test Configuration

• Timeout: 30 seconds per test
• Retries: 2 on CI, 0 locally
• Browsers: Chromium, Firefox, WebKit, Mobile Chrome, Mobile Safari
• Viewport: 1366x900
• Test ID Attribute: data-testid

AI Test Agents

Three AI agents for automated test workflows:

Agent	Input	Output
Planner	App URL + seed test	specs/*.md test plans
Generator	Test plan	tests/*.spec.ts files
Healer	Failing test	Fixed test file

Usage

1. Planner: Explore app and create test plans in specs/
2. Generator: Transform plans into Playwright tests
3. Healer: Debug and fix failing tests

Agent definitions are in .github/agents/ with prompts in .github/prompts/.

Security

• URL validation: Only http:// and https:// protocols allowed
• UUID validation: All session/page IDs validated
• Rate limiting: Configurable MAX_SESSIONS_PER_MINUTE
• Session isolation: Each browser context is isolated
• Script restrictions: Only safe, read-only JavaScript evaluation

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow the coding standards in .github/copilot-instructions.md
4. Run linting and type checking (npm run lint && npm run type-check)
5. Ensure tests pass (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Adding a New Tool

1. Add method to action class in src/playwright/actions/
2. Register in handler file in src/server/handlers/
3. Add schemas to schemas.ts if new input shapes needed
4. Add tests for the new functionality

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Playwright - Browser automation framework
• Model Context Protocol - AI assistant protocol
• axe-core - Accessibility testing engine