MCP Browser Automation Server

A universal Model Context Protocol (MCP) server for AI-driven browser automation with Playwright. Inspired by Microsoft Playwright MCP and Browser-Use, this server provides comprehensive browser automation capabilities for web scraping, testing, accessibility audits, and automated workflows.

Features

🌐 Browser Automation & Use

• Navigation: Automatische Navigation zu URLs mit konfigurierbaren Optionen
• Interaktion: Click, Type, Select, Hover, Scroll Aktionen
• Content Extraction: Strukturierte Extraktion von Text, Links, Bildern und Metadata
• Form Automation: Intelligentes Ausfüllen von Formularen (Input, Select, Checkbox, Radio)
• Wait Conditions: Warten auf Elemente, Zustände oder JavaScript-Bedingungen
• Screenshots: Vollseiten- oder Element-spezifische Screenshots
• JavaScript Evaluation: Ausführung von JavaScript im Browser-Kontext
• Accessibility Tree: Strukturierte Seitenanalyse wie Microsoft Playwright MCP
• State Management: Cookies, localStorage, sessionStorage Management
• PDF Generation: Konvertierung von Webseiten zu PDF
• Network Monitoring: Request/Response Tracking

♿ Accessibility Testing

• axe-core Integration: WCAG 2.1 AA/AAA Compliance Testing
• Kontrast-Prüfung: Automatische Farbkontrast-Validierung
• Keyboard Navigation: Test der Tastatur-Navigation und Fokus-Management

🔒 Privacy & Security Testing

• Cookie Scanning: GDPR-compliant cookie analysis and categorization
• Data Collection Analysis: Review of forms and privacy policies
• Security Testing: Validation of security features and encryption
• Privacy Compliance: GDPR, CCPA, and other privacy regulation checks

⚡ Performance Testing

• Lighthouse Integration: Comprehensive Performance Audits
• Core Web Vitals: LCP, FID, CLS Messungen
• Netzwerk-Analyse: Request-Monitoring und Optimierungsempfehlungen

👁️ Visual Regression Testing

• Screenshot Comparison: Pixel-genaue Vergleiche mit Baselines
• Multi-Viewport Testing: Tests für Desktop, Tablet, Mobile
• Difference Visualization: Automatische Diff-Generierung

📁 Project Structure

mcp-browser-use/
├── bin/                    # Executable scripts
│   └── interactive-browser.ts     # Interactive CLI
├── docs/                   # Documentation
│   ├── INTERACTIVE.md             # Interactive mode guide
│   ├── EXAMPLES.md                # Example usage guide
│   └── comprehensive-frontend-test-report.md
├── examples/               # Example scripts
│   ├── basic/                     # Simple examples
│   ├── advanced/                  # Advanced features
│   └── web-apps/                  # Real-world web app tests
├── src/                    # Source code
│   ├── index.ts                   # MCP server entry
│   └── services/                  # Browser automation services
├── test-output/            # Generated files (gitignored)
│   ├── *.png                      # Screenshots
│   └── *.pdf                      # PDF exports
└── dist/                   # Compiled output (gitignored)

Installation

cd /opt/mcps/mcp-frontend-testing
npm install
npm run build

🚀 Quick Start

Interactive Mode

# Start interactive browser CLI
npm run interactive

# Or with visible browser
DISPLAY=:99 xvfb-run -a npm run interactive

See Interactive Mode Guide for details.

Example Scripts

# Basic example
npm run test:basic

# Web app test
npm run test:webapp

# Run specific example
npx tsx examples/web-apps/test-advanced.ts

See Examples Guide for all examples.

Claude Code Integration

Add this MCP server to your Claude Code configuration:

{
  "mcpServers": {
    "browser-automation": {
      "command": "node",
      "args": ["/opt/mcps/mcp-frontend-testing/dist/index.js"],
      "env": { "NODE_ENV": "production" }
    }
  }
}

Verwendung

Browser Navigation & Content Extraction

// Navigate to a website
await claude.useTool('browser_navigate', {
  url: 'https://example.com',
  options: {
    waitUntil: 'networkidle',
    viewport: { width: 1280, height: 720 }
  }
});

// Extract structured content
await claude.useTool('browser_extract_content', {
  text: true,
  links: true,
  images: true,
  metadata: true
});

// Fill form automatically
await claude.useTool('browser_fill_form', {
  formData: {
    '#email': 'user@example.com',
    '#password': 'secretPassword',
    '#remember-me': 'true'
  },
  submitSelector: '#login-button'
});

// Wait for element or condition
await claude.useTool('browser_wait_for', {
  selector: '#dashboard',
  state: 'visible',
  timeout: 30000
});

// Get accessibility tree (Microsoft Playwright MCP style)
await claude.useTool('browser_get_accessibility_tree', {
  selector: '#main-content'
});

// Get browser state
await claude.useTool('browser_get_state');

// Set browser state (cookies, storage)
await claude.useTool('browser_set_state', {
  cookies: [
    { name: 'session_id', value: 'abc123', domain: 'example.com' }
  ],
  localStorage: {
    'user_preferences': '{"theme":"dark"}'
  }
});

// Generate PDF
await claude.useTool('browser_generate_pdf', {
  path: './output/page.pdf',
  format: 'A4',
  landscape: false
});

// Monitor network requests
await claude.useTool('browser_monitor_network', {
  enable: true
});

Accessibility Testing

// Run WCAG compliance scan
await claude.useTool('accessibility_scan', {
  tags: ['wcag2aa', 'wcag21aa'],
  selector: '#main-content'
});

// Check color contrast
await claude.useTool('accessibility_check_contrast', {
  level: 'AA'
});

Privacy Compliance

// Scan cookies for GDPR compliance
await claude.useTool('privacy_scan_cookies', {
  checkConsent: true,
  categorize: true
});

// Test panic button functionality
await claude.useTool('privacy_test_panic_button', {
  selector: '#panic-button',
  verifyDeletion: true
});

Performance Testing

// Run Lighthouse audit
await claude.useTool('performance_lighthouse', {
  categories: ['performance', 'accessibility', 'best-practices'],
  device: 'mobile',
  throttling: 'mobile3G'
});

// Measure Core Web Vitals
await claude.useTool('performance_measure_vitals', {
  interactions: [
    { action: 'click', selector: '#login-button' }
  ]
});

Visual Regression Testing

// Create baseline screenshots
await claude.useTool('visual_create_baseline', {
  testName: 'login-page',
  viewports: [
    { width: 1920, height: 1080, name: 'desktop' },
    { width: 375, height: 667, name: 'mobile' }
  ]
});

// Compare with baseline
await claude.useTool('visual_compare', {
  baselinePath: './visual-tests/baselines/login-page-desktop-1920x1080.png',
  threshold: 0.01,
  maskSelectors: ['.dynamic-timestamp', '.user-avatar']
});

Advanced Use Cases

E-Commerce Testing

// Add product to cart
await claude.useTool('browser_interact', {
  action: 'click',
  selector: '.add-to-cart-button'
});

// Verify cart count
await claude.useTool('browser_evaluate', {
  script: `
    const cartBadge = document.querySelector('.cart-count');
    return { itemCount: parseInt(cartBadge.textContent) };
  `
});

Form Automation

// Fill multi-step form
await claude.useTool('browser_fill_form', {
  formData: {
    '#email': 'user@example.com',
    '#password': 'SecurePass123',
    '#terms-checkbox': 'true'
  }
});

await claude.useTool('browser_interact', {
  action: 'click',
  selector: '#submit-button'
});

Authentication Flow Testing

// Test login flow
await claude.useTool('browser_navigate', {
  url: 'https://example.com/login'
});

await claude.useTool('browser_fill_form', {
  formData: {
    '#username': 'testuser',
    '#password': 'testpass'
  },
  submitSelector: '#login-button'
});

await claude.useTool('browser_wait_for', {
  selector: '#dashboard',
  state: 'visible',
  timeout: 30000
});

Testing Workflows

1. Complete Frontend Audit

# Navigation + Accessibility + Privacy + Performance
1. browser_navigate → URL
2. accessibility_scan → WCAG compliance
3. privacy_scan_cookies → GDPR compliance
4. performance_lighthouse → Performance audit
5. visual_create_baseline → Visual regression baseline

2. Privacy Compliance Validation

# Comprehensive privacy testing
1. privacy_scan_cookies → Cookie compliance
2. privacy_check_data_collection → Data collection analysis
3. privacy_test_panic_button → Emergency deletion
4. privacy_test_encryption → Encryption validation

3. Multi-Device Testing

# Cross-device compatibility
1. visual_create_baseline → Desktop baseline
2. browser_navigate → Mobile viewport
3. visual_compare → Mobile vs Desktop
4. accessibility_keyboard_navigation → Mobile accessibility

Konfiguration

Environment Variables

NODE_ENV=production
PLAYWRIGHT_BROWSERS_PATH=/path/to/browsers
LIGHTHOUSE_CHROME_PATH=/path/to/chrome

Browser Configuration

• Chromium: Standard für Performance-Tests
• Firefox: Alternative für Cross-Browser-Tests
• Webkit: Safari-Kompatibilität

Visual Testing Configuration

// Baseline-Verzeichnisse
const config = {
  baselineDir: './visual-tests/baselines',
  actualDir: './visual-tests/actual',
  diffDir: './visual-tests/diffs',
  threshold: 0.01 // 1% Unterschied erlaubt
};

Troubleshooting

Browser nicht verfügbar

# Playwright Browser installieren
npx playwright install chromium

Lighthouse Fehler

# Chrome für Lighthouse sicherstellen
npm install -g lighthouse

Visual Tests fehlschlagen

# Baselines neu erstellen
rm -rf ./visual-tests/baselines/*
# Dann visual_create_baseline verwenden

Integration in CI/CD

# .github/workflows/frontend-testing.yml
name: Frontend Testing
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install dependencies
        run: |
          cd mcp-frontend-testing
          npm install
          npm run build

      - name: Install browsers
        run: npx playwright install

      - name: Run MCP Frontend Tests
        run: |
          # Start Claude Code with MCP server
          # Execute test suite via Claude
          node test-runner.js

Entwicklung

Neue Tools hinzufügen

1. Service in src/services/ erweitern
2. Tool in src/index.ts registrieren
3. Schema in ListToolsRequestSchema definieren
4. Handler in CallToolRequestSchema implementieren

Testing der MCP Server

npm run test
npm run lint
npm run typecheck

Lizenz

MIT License - siehe LICENSE Datei für Details.

Support

For questions or issues:

• GitHub Issues: https://git.customable.host/customable-mcp/browser-use
• MCP Documentation: https://modelcontextprotocol.io/docs

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Repository

• Git: https://git.customable.host/customable-mcp/browser-use