HaolongChen/playwright-mcp-vercel

Playwright MCP Vercel

A serverless Playwright MCP (Model Context Protocol) server deployed on Vercel. This project provides an HTTP endpoint that proxies requests to the Playwright MCP tool, enabling browser automation capabilities through a simple REST API.

🌟 Overview

This server acts as a bridge between HTTP clients and the Playwright MCP tool, allowing you to:

• Perform browser automation tasks via HTTP requests
• Run Playwright scripts in a serverless environment
• Integrate browser automation into AI workflows and agents
• Access Playwright capabilities without local installation

🚀 Features

• Serverless Deployment: Runs on Vercel's edge network for global availability
• Simple REST API: Single /mcp endpoint for all Playwright operations
• Error Handling: Comprehensive error responses and timeout management
• Health Checks: Built-in health check endpoint for monitoring
• Auto-scaling: Leverages Vercel's automatic scaling capabilities

📋 Prerequisites

Before deploying this project, ensure you have:

• Node.js 18.x or higher installed locally (for development)
• A Vercel account (free tier works)
• Git installed
• (Optional) Vercel CLI for command-line deployment

🛠️ Setup Instructions

1. Clone the Repository

git clone https://github.com/HaolongChen/playwright-mcp-vercel.git
cd playwright-mcp-vercel

2. Install Dependencies

npm install

3. Test Locally (Optional)

# Start the development server
npm run dev

# Test health check
curl http://localhost:3000

🚀 Deployment to Vercel

Method 1: Deploy via Vercel Dashboard (Recommended for Beginners)

1. Push to GitHub (if you haven't already):

   git add .
   git commit -m "Initial commit"
   git push origin main
   

2. Import to Vercel:

   • Go to Vercel Dashboard
   • Click "Add New..." → "Project"
   • Select "Import Git Repository"
   • Choose your playwright-mcp-vercel repository
   • Click "Import"

3. Configure Project (use defaults):

   • Framework Preset: Other
   • Root Directory: ./
   • Build Command: (leave empty)
   • Output Directory: (leave empty)
   • Install Command: npm install

4. Deploy:

   • Click "Deploy"
   • Wait 2-3 minutes for deployment to complete
   • Your app will be live at https://your-project-name.vercel.app

Method 2: Deploy via Vercel CLI

1. Install Vercel CLI (if not already installed):

   npm install -g vercel
   

2. Login to Vercel:

   vercel login
   

3. Deploy to Production:

   # First deployment (follow prompts)
   vercel --prod
   
   # Subsequent deployments
   vercel --prod
   

4. The CLI will ask you:

   • Set up and deploy? Y
   • Which scope? (select your account)
   • Link to existing project? N (first time)
   • What's your project's name? playwright-mcp-vercel
   • In which directory is your code located? ./
   • Want to override the settings? N

5. Note your deployment URL from the CLI output.

Method 3: One-Click Deploy

Click the button above to deploy directly to your Vercel account.

🔧 Environment Variables

This project currently doesn't require environment variables for basic operation. The following are pre-configured in vercel.json:

• NODE_ENV: Set to production automatically
• PORT: Managed by Vercel (no configuration needed)

Adding Custom Environment Variables

If you need to add custom environment variables:

1. Via Vercel Dashboard:

   • Go to your project → Settings → Environment Variables
   • Add your variables for Production, Preview, and/or Development
   • Redeploy to apply changes

2. Via Vercel CLI:

   vercel env add VARIABLE_NAME production
   

📖 Usage Examples

Health Check

Check if the server is running:

curl https://your-project-name.vercel.app/

Response:

{
  "status": "ok",
  "message": "Playwright MCP Server is running"
}

Making MCP Requests

Send MCP commands to the /mcp endpoint:

Example 1: Basic MCP Request

curl -X POST https://your-project-name.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/list"
  }'

Example 2: Navigate to a Webpage

curl -X POST https://your-project-name.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "playwright_navigate",
      "arguments": {
        "url": "https://example.com"
      }
    }
  }'

Example 3: Take a Screenshot

curl -X POST https://your-project-name.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "playwright_screenshot",
      "arguments": {
        "name": "example-screenshot"
      }
    }
  }'

Example 4: Using with JavaScript/Node.js

const response = await fetch('https://your-project-name.vercel.app/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    method: 'tools/list'
  })
});

const data = await response.json();
console.log(data);

Example 5: Using with Python

import requests

url = "https://your-project-name.vercel.app/mcp"
payload = {
    "method": "tools/list"
}

response = requests.post(url, json=payload)
print(response.json())

🔍 API Reference

Endpoints

GET /

Health check endpoint.

Response:

• 200 OK: Server is running
• Returns: { "status": "ok", "message": "Playwright MCP Server is running" }

POST /mcp

Main MCP endpoint for Playwright operations.

Headers:

• Content-Type: application/json

Request Body:

• MCP protocol-compliant JSON payload

Response:

• 200 OK: Request processed successfully
• 400 Bad Request: Invalid request body
• 500 Internal Server Error: Playwright MCP process failed
• 504 Gateway Timeout: Request timeout (>30 seconds)

Error Response Format:

{
  "error": "Error Type",
  "message": "Detailed error message",
  "details": "Additional context (if available)"
}

🐛 Troubleshooting

Common Issues

1. Deployment Fails

Problem: Vercel deployment fails with build errors.

Solution:

• Ensure package.json has correct dependencies
• Verify Node.js version is ≥18.0.0
• Check Vercel build logs for specific errors
• Try clearing Vercel cache: Settings → General → Clear Cache → Redeploy

2. 504 Gateway Timeout

Problem: Requests timeout after 30 seconds.

Solution:

• The default timeout is 30 seconds (60 seconds max on Vercel)
• Optimize your Playwright scripts to run faster
• Consider breaking complex operations into smaller requests
• For longer operations, upgrade to Vercel Pro for extended timeouts

3. Memory Limit Exceeded

Problem: Function runs out of memory.

Solution:

• Current memory limit: 1024 MB (configured in vercel.json)
• Upgrade to Vercel Pro for 3008 MB memory limit
• Optimize your Playwright scripts to use less memory
• Close browser contexts when done

4. "playwright-mcp not found" Error

Problem: Server can't find the playwright-mcp executable.

Solution:

• Ensure playwright-mcp is installed as a dependency
• Add to package.json if missing:

  "dependencies": {
    "playwright-mcp": "latest"
  }
  

• Redeploy after updating dependencies

5. CORS Issues

Problem: Browser requests blocked by CORS policy.

Solution: Add CORS middleware to server.js:

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Headers', 'Content-Type');
  res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
  if (req.method === 'OPTIONS') {
    return res.sendStatus(200);
  }
  next();
});

6. Slow Response Times

Problem: Requests take longer than expected.

Solution:

• First request after idle time may be slower (cold start)
• Vercel functions "warm up" after initial use
• Consider using Vercel Pro for faster cold starts
• Region is set to iad1 (Virginia) - change in vercel.json if needed

Getting Help

If you encounter issues not covered here:

1. Check Vercel Documentation
2. Review Playwright MCP Repository
3. Check Vercel function logs: Project → Deployments → Click deployment → View Function Logs
4. Open an issue on this repository

📁 Project Structure

playwright-mcp-vercel/
├── server.js          # Express server with MCP endpoint
├── package.json       # Dependencies and scripts
├── vercel.json        # Vercel deployment configuration
└── README.md          # This file

⚙️ Configuration Files

vercel.json

Configures Vercel deployment settings:

• maxDuration: 60 seconds (function timeout)
• memory: 1024 MB (allocated memory)
• maxLambdaSize: 50 MB (deployment bundle size)
• region: iad1 (US East)

package.json

Defines Node.js version, dependencies, and scripts:

• Node.js: ≥18.0.0 required
• Main dependency: Express.js for HTTP server

🔒 Security Considerations

• Rate Limiting: Consider adding rate limiting for production use
• Authentication: Add API key authentication for sensitive operations
• Input Validation: Validate and sanitize all MCP request payloads
• HTTPS Only: Vercel enforces HTTPS by default
• Environment Variables: Use Vercel environment variables for secrets

📊 Monitoring

Monitor your deployment:

1. Vercel Analytics: Enable in Project Settings → Analytics
2. Function Logs: View real-time logs in Vercel dashboard
3. Error Tracking: Integrate with Sentry or similar services

🚀 Advanced Usage

Custom Domains

Add a custom domain in Vercel:

1. Go to Project → Settings → Domains
2. Add your domain
3. Configure DNS records as instructed

Environment-Specific Deployments

# Deploy to preview environment
vercel

# Deploy to production
vercel --prod

Continuous Deployment

Vercel automatically deploys:

• Production: Pushes to main branch
• Preview: Pull requests and other branches

📄 License

MIT License - see package.json for details

👤 Author

Haolong Chen

• GitHub: @HaolongChen

🙏 Acknowledgments

• Playwright MCP Server - The underlying MCP implementation
• Vercel - Serverless deployment platform
• Playwright - Browser automation framework

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Happy automating! 🎭✨