🎭 Playwright MCP Automation

Bridge the gap between AI assistants and browser automation — Control Playwright directly from natural language prompts using the Model Context Protocol (MCP).

🌟 Overview

This project integrates Playwright with the Model Context Protocol (MCP), enabling AI tools like GitHub Copilot, Claude Desktop, or Cursor to perform browser automation tasks through simple conversational prompts.

Why MCP + Playwright?

• Natural Language Control: Describe what you want instead of writing test code

• AI-Powered Testing: Let AI assistants handle browser interactions

• Rapid Prototyping: Test ideas without manual script writing

• Flexible Automation: Combine vision-based clicking, PDF generation, and assertions

✨ What You Can Do

Simply ask your AI assistant:

"Open Google and search for Playwright"
"Verify the title contains 'Playwright' and take a screenshot"
"Click the Docs tab and generate a PDF of the page"
"Find the download button using visual recognition and click it"

The AI translates your request → MCP Protocol → Browser Actions → Results ✨

No need to run

📁 Project Structure

Playwright_MCP/
├── tests/
│   └── mcp-playwright.spec.ts    # Example Playwright test suite
├── scripts/
│   └── run-via-mcp.js             # Manual MCP client (optional)
├── mcp.config.json                # MCP server configuration
├── playwright.config.ts           # Playwright configuration
├── package.json                   # Dependencies
└── README.md                      # This file

🚀 Getting Started

Prerequisites

Ensure you have the following installed:

Installation

1. Clone or navigate to your project directory

2. Install dependencies

   npm install

3. Install Playwright browsers (if not already installed)

   npx playwright install

⚙️ Configuration

MCP Server Setup

The MCP configuration is defined in mcp.config.json:

{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--caps=vision,pdf,testing,tracing"
      ],
      "env": {}
    }
  }
}

Enabled Capabilities

🎯 Usage

Method 1: AI Assistant Integration (Recommended)

1. Start the MCP server in a terminal:

   npx @playwright/mcp@latest --caps=vision,pdf,testing,tracing --output-dir=playwright-mcp-output

   You should see:

   Listening on http://localhost:8931

   ⚠️ Keep this terminal running — the MCP server must stay active

2. Open your AI tool (Claude Desktop, Cursor, GitHub Copilot, etc.)

3. Issue natural language commands:

   "Open google.com, search 'Playwright', verify results appear, and take a screenshot"

4. Watch the magic happen — the AI will:

   • Connect to your MCP server

   • Control the browser

   • Execute the automation

   • Return results/screenshots

Method 2: Manual MCP Client (Testing)

If you want to test MCP functionality without an AI assistant:

node scripts/run-via-mcp.js

This script will:

• Launch a browser via MCP

• Navigate to Google

• Search for "Playwright"

• Save a screenshot locally

Method 3: Traditional Playwright Tests

Run Playwright tests the standard way (without MCP):

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

📦 Output & Artifacts

All generated files are saved to:

playwright-mcp-output/

Example artifacts:

• google-playwright-search.png — Screenshots

• page.pdf — PDF exports

• trace.zip — Playwright trace files

🔧 Troubleshooting

Debug Mode

Run the MCP server with verbose logging:

DEBUG=* npx @playwright/mcp@latest --caps=vision,pdf,testing,tracing

🎯 Roadmap & Future Enhancements

• Automate complex login flows via MCP

• Advanced cursor-based interactions

• File download verification

• Trace log streaming to AI assistants

• Multi-browser support (Chromium, Firefox, WebKit)

• CI/CD pipeline integration

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs

• Suggest new features

• Submit pull requests

📄 License

This project is licensed under the MIT License.

🔗 Resources

• Playwright Documentation

• Model Context Protocol Specification

• Playwright MCP Package

Built with ❤️ using Playwright & MCP