🎭 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

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

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)

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

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

• Playwright Documentation
• Model Context Protocol Specification
• Playwright MCP Package

---

Built with ❤️ using Playwright & MCP