michaail/playwright-mcp-docker

Playwright MCP Docker

A Docker-based setup for running Microsoft's Playwright MCP (Model Context Protocol) server with Chrome browser automation in a containerized environment.

Overview

This project provides a complete Docker environment for running Playwright browser automation through the MCP (Model Context Protocol) interface. It includes:

• Playwright MCP Server: Microsoft's official Playwright MCP server for browser automation
• Chromium Browser: Pre-configured Chrome/Chromium with optimized flags for containerized environments
• Custom Chrome Wrapper: A wrapper script that dynamically locates and configures Chrome with proper flags
• HTTP API Interface: RESTful API endpoints for browser automation tasks
• Volume Persistence: Configuration and output file persistence

Architecture

┌─────────────────────────────────────────┐
│             Docker Container            │
│                                         │
│  ┌─────────────────┐                    │
│  │  MCP Server     │                    │
│  │  (Port 8831)    │◄──── HTTP API      │
│  └─────────────────┘                    │
│           │                             │
│           ▼                             │
│  ┌─────────────────┐                    │
│  │ chrome-wrapper  │                    │
│  │      .sh        │                    │
│  └─────────────────┘                    │
│           │                             │
│           ▼                             │
│  ┌─────────────────┐                    │
│  │   Chromium      │                    │
│  │   Browser       │                    │
│  └─────────────────┘                    │
└─────────────────────────────────────────┘

Features

• Headless Browser Automation: Full Playwright capabilities in a containerized environment
• HTTP API Interface: Easy integration with external applications
• Custom Chrome Configuration: Optimized Chrome flags for Docker environments
• Volume Mounting: Persistent configuration and output storage
• Resource Optimization: Shared memory and GPU acceleration disabled for stability
• Cross-Platform: Works on macOS, Linux, and Windows with Docker

Quick Start

Prerequisites

• Docker and Docker Compose installed
• Port 8831 available on your host machine

1. Clone and Navigate

git clone <your-repository-url>
cd playwright-mcp-on-docker-vnc

2. Build and Run

# Build and start the container
docker compose up --build

# Or run in detached mode
docker compose up --build -d

3. Verify Installation

The MCP server will be available at http://localhost:8831

Check container logs:

docker compose logs -f

Configuration

config.json

The main configuration file located at config/config.json:

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "executablePath": "/usr/local/bin/chrome-wrapper.sh"
    },
    "contextOptions": {}
  },
  "server": {
    "host": "0.0.0.0",
    "port": 8831
  },
  "outputDir": "/config/output",
  "imageResponses": "omit"
}

Chrome Wrapper Configuration

The chrome-wrapper.sh script automatically configures Chrome with optimal flags:

• --no-sandbox: Disables Chrome sandbox for Docker compatibility
• --disable-dev-shm-usage: Uses /tmp instead of /dev/shm for shared memory
• --disable-gpu: Disables GPU acceleration
• --user-data-dir=/tmp/shared-browser-data: Sets user data directory
• --disable-features=Vulkan: Disables Vulkan features
• --use-gl=swiftshader: Uses software-based GL implementation

Usage Examples

Integration with MCP Clients

This server is compatible with MCP clients such as Claude Desktop, VS Code extensions, or custom applications that support the MCP protocol.

Example VS Code MCP configuration (mcp.json):

{
  "servers": {
    "playwright": {
      "url": "http://localhost:8831/mcp"
    }
  }
}

File Structure

playwright-mcp-on-docker-vnc/
├── docker-compose.yml          # Docker Compose configuration
├── Dockerfile                  # Container build instructions
├── startup.sh                  # Container startup script
├── chrome-wrapper.sh           # Chrome executable wrapper
├── config/
│   ├── config.json            # MCP server configuration
│   └── output/                # Output directory for screenshots, etc.
│       └── .gitkeep
└── README.md                  # This file

Troubleshooting

Common Issues

1. Port 8831 already in use

   # Check what's using the port
   lsof -i :8831
   
   # Kill the process or change the port in docker-compose.yml
   

2. Chrome fails to start

   • Check Docker logs: docker compose logs
   • Ensure sufficient memory allocation
   • Verify chrome-wrapper.sh has execute permissions

3. Container exits immediately

   # Check container logs
   docker compose logs
   
   # Run interactively for debugging
   docker run -it playwright-mcp-vnc /bin/bash
   

Debug Mode

Run the container interactively for debugging:

# Build the image
docker compose build

# Run interactively
docker run -it --rm \
  -p 8831:8831 \
  -v $(pwd)/config:/config \
  playwright-mcp-vnc /bin/bash

Development

Building Custom Images

# Build with custom tag
docker build -t my-playwright-mcp .

# Run with custom image
docker run -p 8831:8831 my-playwright-mcp

Modifying Chrome Flags

Edit chrome-wrapper.sh to add or modify Chrome startup flags:

exec "$REAL_CHROME" \
  --no-sandbox \
  --disable-dev-shm-usage \
  --your-custom-flag \
  "$@"

Configuration Changes

Modify config/config.json and restart the container:

docker compose restart

Performance Considerations

• Memory: Allocate at least 2GB RAM for the container
• Shared Memory: The setup uses /tmp instead of /dev/shm to avoid memory issues
• CPU: Browser automation can be CPU-intensive; consider dedicated resources
• Network: Ensure stable internet connection for web page loading

Security Notes

• The container runs with --no-sandbox flag for Chrome compatibility
• Only expose port 8831 to trusted networks
• Consider using authentication if deploying in production
• Regularly update the base Playwright image for security patches

Contributing

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

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Microsoft Playwright - Browser automation framework
• Playwright MCP - Official MCP server implementation
• Docker - Containerization platform

Support

For issues and questions:

1. Check the Troubleshooting section
2. Review Playwright MCP documentation
3. Open an issue in this repository

Note: This setup is optimized for development and testing environments. For production deployments, consider additional security hardening and resource optimization.