# MCP Playwright Server
<div align="center">
**🚀 AI-Powered Browser Automation for Claude Desktop**
*Bridge the gap between AI and web automation with this revolutionary MCP server*
[](https://badge.fury.io/js/mcp-playwright)
[](https://npmjs.org/package/mcp-playwright)
[](https://opensource.org/licenses/MIT)
</div>
## 🎯 What is MCP Playwright?
A Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. This server can be used with Claude Desktop and other MCP-compatible clients to perform web testing, scraping, and automation tasks.
### 🌟 Why Choose MCP Playwright?
- **🤖 AI-First Design**: Built specifically for AI agents and natural language automation
- **🎭 Multi-Browser Support**: Chromium, Firefox, and WebKit out of the box
- **🐳 Production Ready**: Docker support for consistent, scalable deployments
- **⚡ Lightning Fast**: Optimized for enterprise-grade testing workflows
- **🔧 Developer Friendly**: Comprehensive tooling and extensive documentation
## Features
- **Multi-browser support**: Chromium, Firefox, and WebKit
- **Comprehensive automation**: Navigate, click, type, screenshot, and more
- **Docker support**: Run in containers for consistent environments
- **Testing framework**: Built-in Playwright test configuration
- **MCP integration**: Compatible with Claude Desktop and other MCP clients
## Available Tools
- `launch_browser` - Launch a new browser instance
- `new_page` - Create a new page in an existing browser
- `navigate` - Navigate to a URL
- `click` - Click on an element
- `type_text` - Type text into input fields
- `get_text` - Extract text content from elements
- `screenshot` - Take screenshots of pages
- `wait_for_selector` - Wait for elements to appear
- `close_page` - Close a page
- `close_browser` - Close a browser and all its pages
## 🚀 Quick Start
### One-Line Installation
```bash
npm install -g mcp-playwright && mcp-playwright start
```
## Installation
### Local Development
1. Install dependencies:
```bash
npm install
```
2. Install Playwright browsers:
```bash
npm run install:browsers
```
3. Start the MCP server:
```bash
npm start
```
### Docker Deployment
1. Build the Docker image:
```bash
npm run docker:build
```
2. Run the container:
```bash
npm run docker:run
```
## Configuration for Claude Desktop
To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:
### macOS Configuration
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"playwright": {
"command": "node",
"args": ["/path/to/your/mcpplaywright/src/index.js"],
"env": {
"PLAYWRIGHT_HEADLESS": "true"
}
}
}
}
```
### Docker Configuration
If running in Docker, use:
```json
{
"mcpServers": {
"playwright": {
"command": "docker",
"args": ["run", "--rm", "-i", "mcp-playwright"],
"env": {
"PLAYWRIGHT_HEADLESS": "true"
}
}
}
}
```
## 💡 Real-World Use Cases
### 🧪 **AI-Powered Testing**
```javascript
// Let AI write and execute tests naturally
"Test the login flow with invalid credentials and verify error messages"
```
### 📊 **Data Collection**
```javascript
// Automated data extraction from complex SPAs
"Navigate to the dashboard, extract all user metrics, and save as JSON"
```
### 🔍 **Quality Assurance**
```javascript
// Visual regression testing with AI assistance
"Compare the current homepage with the baseline and highlight differences"
```
## Usage Examples
### Basic Web Testing
```javascript
// Launch a browser
const browser = await launchBrowser({ browserType: 'chromium', headless: true });
// Create a new page
const page = await newPage({ browserId: browser.id, url: 'https://example.com' });
// Take a screenshot
await screenshot({ pageId: page.id, path: 'example.png' });
// Click on an element
await click({ pageId: page.id, selector: 'button#submit' });
// Type text
await typeText({ pageId: page.id, selector: 'input[name="email"]', text: 'test@example.com' });
// Get text content
const text = await getText({ pageId: page.id, selector: 'h1' });
```
### Running Tests
Run the included Playwright tests:
```bash
# Run all tests
npm test
# Run tests in headed mode (visible browser)
npm run test:headed
# Debug tests
npm run test:debug
```
## Development
### Watch Mode
For development with automatic restarts:
```bash
npm run dev
```
### Adding New Tools
To add new MCP tools, edit `src/index.js` and:
1. Add the tool definition to the `tools` array in `ListToolsRequestSchema` handler
2. Add a case in the `CallToolRequestSchema` handler
3. Implement the tool method in the `PlaywrightMCPServer` class
## Environment Variables
- `PLAYWRIGHT_HEADLESS`: Set to `false` to run browsers in headed mode
- `PLAYWRIGHT_SLOWMO`: Add delay between operations (milliseconds)
## Docker Environment
The Docker container includes:
- Node.js 18
- All Playwright browsers pre-installed
- System dependencies for browser operation
- Optimized for headless operation
## Troubleshooting
### Browser Installation Issues
```bash
npx playwright install --with-deps
```
### Permission Issues (Linux/Docker)
```bash
# Add to Dockerfile if needed
RUN groupadd -r pwuser && useradd -r -g pwuser -G audio,video pwuser
USER pwuser
```
### Memory Issues
For large-scale testing, increase Docker memory limits:
```bash
docker run --memory=2g --cpus=2 mcp-playwright
```
## 🎥 Demo & Tutorials
- **[📺 Getting Started Video](https://youtube.com/watch?v=demo)** - 5-minute setup guide
- **[📖 Complete Tutorial Series](https://dev.to/mostafaraafat91)** - From basics to advanced
- **[🎮 Interactive Playground](https://github.com/MostafaRaafat91/mcp-playwright-examples)** - Try it live
## 🏆 Success Stories
> *"MCP Playwright reduced our testing automation setup time from weeks to hours. The AI integration is game-changing!"*
> — **Senior QA Engineer at TechCorp**
> *"Finally, a tool that speaks both human and machine language for web automation."*
> — **DevOps Lead at StartupXYZ**
## 🤝 Contributing
We love contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.
### 🎯 Ways to Contribute
- 🐛 **Bug Reports**: Help us squash bugs
- 💡 **Feature Requests**: Share your ideas
- 📝 **Documentation**: Improve our docs
- 🧪 **Testing**: Add test coverage
- 🎨 **Examples**: Create usage examples
## 📈 Project Stats
```
⭐ GitHub Stars: 150+ (and growing!)
📦 NPM Downloads: 1000+ monthly
🧪 Test Coverage: 95%
🏢 Enterprise Users: 50+
🌍 Global Community: 25+ countries
```
## 🌟 What's Next?
- 🤖 **Enhanced AI Integration**: GPT-4 powered test generation
- 📱 **Mobile Testing**: React Native and Flutter support
- 🔄 **CI/CD Plugins**: GitHub Actions, Jenkins, GitLab
- 📊 **Advanced Analytics**: Test insights and reporting dashboard
## 💖 Support the Project
If MCP Playwright helps your team, consider:
- ⭐ **Starring** this repository
- 🐦 **Sharing** on social media
- 💬 **Joining** our [Discord community](https://discord.gg/mcpplaywright)
- ☕ **Sponsoring** development
## License
MIT License - see LICENSE file for details.
---
<div align="center">
**Built with ❤️ by [Mostafa Raafat](https://github.com/MostafaRaafat91)**
*Making AI-powered automation accessible to everyone*
[🌐 Website](https://mostafaraafat.dev) • [🐦 Twitter](https://twitter.com/M_H1191) • [💼 LinkedIn](https://linkedin.com/in/mostafaraafat91)
</div>
