Playwright MCP Automation

# 🎭 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** ```bash npm install ``` 3. **Install Playwright browsers** (if not already installed) ```bash npx playwright install ``` --- ## ⚙️ Configuration ### MCP Server Setup The MCP configuration is defined in `mcp.config.json`: ```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: ```bash 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: ```bash 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): ```bash 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: ```bash 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](https://playwright.dev/) - [Model Context Protocol Specification](https://modelcontextprotocol.io/) - [Playwright MCP Package](https://www.npmjs.com/package/@playwright/mcp) --- **Built with ❤️ using Playwright & MCP**