Playwright MCP Proxy Server

You are running a proxy that sits between your MCP client and the Playwright MCP service. It intercepts large binary data like screenshots and PDFs, stores them as blobs, and returns references to those blobs to save tokens while preserving full data when needed.

How to use

Use this MCP server to enable browser automation with Playwright while efficiently handling large binary data. Your MCP client connects to the proxy via stdio, and the proxy forwards tool calls to Playwright MCP, automatically storing large data as blobs and returning references when appropriate. Retrieve the blob data later with the provided tools if you need the original binary content.

How to install

Prerequisites and runtime requirements are:

• Python 3.10 or higher
• Node.js 18+ for Playwright MCP
• uv package manager (recommended)
• Docker (optional, for containerized deployment)

uv install prerequisites
# This step ensures the uv tool is available on your system

# Note: The exact prerequisites installation steps depend on your OS. Ensure Python 3.10+ and Node.js 18+ are installed before proceeding.

Step-by-step setup using the local runtime (no Docker):

1. Clone the project and enter the directory.
2. Install dependencies using the uv tool.
3. Create your environment file from the example and customize it.
4. Start the proxy server.

git clone <this-repo> playwright-proxy-mcp
cd playwright-proxy-mcp

uv sync

cp .env.example .env
# Edit .env with your configuration (defaults are sensible)

uv run playwright-proxy-mcp

If you prefer containerized deployment, you can use Docker Compose. Build and start the services with:

docker compose up -d

Configuration

Configure the proxy via environment variables in your environment file. The following settings are used to control Playwright behavior and blob storage.

PLAYWRIGHT_BROWSER=chromium
PLAYWRIGHT_HEADLESS=true
PLAYWRIGHT_CAPS=vision,pdf
PLAYWRIGHT_TIMEOUT_ACTION=5000
PLAYWRIGHT_TIMEOUT_NAVIGATION=60000

BLOB_STORAGE_ROOT=/mnt/blob-storage
BLOB_MAX_SIZE_MB=500
BLOB_TTL_HOURS=24
BLOB_SIZE_THRESHOLD_KB=50
BLOB_CLEANUP_INTERVAL_MINUTES=60

Environment variable descriptions and typical values are:

• PLAYWRIGHT_BROWSER: Browser to use (chromium, firefox, webkit)
• PLAYWRIGHT_HEADLESS: Run in headless mode
• PLAYWRIGHT_CAPS: Capabilities to enable (e.g., vision, pdf)
• PLAYWRIGHT_TIMEOUT_ACTION: Action timeout in milliseconds
• PLAYWRIGHT_TIMEOUT_NAVIGATION: Navigation timeout in milliseconds
• BLOB_STORAGE_ROOT: Path to the blob storage directory
• BLOB_MAX_SIZE_MB: Maximum size of a single blob in megabytes
• BLOB_TTL_HOURS: Time-to-live for blobs in hours
• BLOB_SIZE_THRESHOLD_KB: Data size threshold to trigger blob storage in kilobytes
• BLOB_CLEANUP_INTERVAL_MINUTES: How often the system cleans up expired blobs (minutes)

Troubleshooting

If the proxy cannot connect or the Playwright environment fails to initialize, check the following common issues.

# Example troubleshooting steps
node --version
npx --version
uv --version
chmod -R 755 /mnt/blob-storage

Notes

The proxy automatically stores large binary data as blobs to reduce token usage. You can retrieve blob data later using provided tools. Ensure blob storage has appropriate permissions and that TTL settings match your retention policy.

Available tools

playwright_navigate

Navigate to a URL using the Playwright MCP proxy tools.

playwright_click

Click an element on the page using Playwright MCP proxy tools.

playwright_fill

Fill a form field during automated interaction.

playwright_screenshot

Capture a screenshot; large results are stored as blobs and returned as references.

playwright_get_visible_text

Retrieve visible text from the page.

get_blob

Retrieve binary data for a blob by its ID.

list_blobs

List available blobs with optional filters like mime type and tags.

delete_blob

Delete a blob from storage.