🎭 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 npx playwright test manually!

📁 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:

Tool	Check Version	Required Version
Node.js	`node --version`	v18.0.0 or higher
npm	`npm --version`	Latest stable
Playwright	`npx playwright --version`	Latest

Installation

Clone or navigate to your project directory
Install dependencies
```
npm install
```
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

Capability	Description
vision	Use coordinates and OCR for element interaction
pdf	Generate PDF snapshots of web pages
testing	Run assertions (visibility, text content, values)
tracing	Collect debug traces for troubleshooting

🎯 Usage

Method 1: AI Assistant Integration (Recommended)

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

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

Issue natural language commands:

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

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

Issue	Solution
`Error: spawn npx ENOENT`	Ensure the MCP server is running in a separate terminal
`Server disconnected`	Restart the MCP server terminal window
`Browser not launching`	Run `npx playwright install` to install browser binaries
`Port 8931 already in use`	Kill the existing MCP process or change the port
`Vision capabilities not working`	Ensure `--caps=vision` is included in server args

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

Built with ❤️ using Playwright & MCP