Playwright MCP HTTP Server

Name: Playwright MCP HTTP Server
Author: mcpmessenger

A standalone HTTP service that wraps the official @playwright/mcp package to provide browser automation capabilities via HTTP endpoints. This service enables the use of Playwright MCP in serverless environments where STDIO-based communication is not possible.

Features

🌐 HTTP-based MCP Protocol - Access Playwright MCP via standard HTTP requests
🚀 Serverless Compatible - Works in serverless/cloud environments (Railway, Render, Fly.io, GCP Cloud Run, etc.)
🔄 MCP v0.1 Compatible - Fully implements the Model Context Protocol specification
🎭 Full Playwright Support - All Playwright browser automation tools available
🐳 Docker Ready - Includes Dockerfile for easy containerization
⚡ Production Ready - Health checks, graceful shutdown, error handling
☁️ Live Deployment - Pre-deployed to Google Cloud Run (see below)

Quick Start

Prerequisites

Node.js 18+ (LTS recommended)
npm or yarn

Installation

# Clone the repository git clone https://github.com/mcpmessenger/playwright-mcp.git cd playwright-mcp # Install dependencies npm install # Build the project npm run build # Start the server npm start

The server will start on port 8931 by default. You can access:

Service Info: http://localhost:8931/
Health Check: http://localhost:8931/health
MCP Endpoint: http://localhost:8931/mcp (POST only)

🚀 Live Production Instance

The service is deployed to Google Cloud Run and ready to use:

Service URL: https://playwright-mcp-http-server-554655392699.us-central1.run.app
Health Check: https://playwright-mcp-http-server-554655392699.us-central1.run.app/health
MCP Endpoint: https://playwright-mcp-http-server-554655392699.us-central1.run.app/mcp (POST only)

You can use the live instance immediately without deploying your own. See Usage Examples below.

Development

# Run in development mode with auto-reload npm run dev

Configuration

Configuration is done via environment variables. Create a .env file or set environment variables:

Variable	Default	Description
`PORT`	`8931`	HTTP server port
`PLAYWRIGHT_BROWSER`	`chromium`	Browser type (chromium, firefox, webkit)
`PLAYWRIGHT_HEADLESS`	`true`	Run browser in headless mode
`LOG_LEVEL`	`info`	Logging level (error, warn, info, debug)
`MAX_SESSIONS`	(unlimited)	Maximum concurrent browser sessions
`SESSION_TIMEOUT`	(none)	Session timeout in seconds
`CORS_ORIGIN`	`*`	CORS allowed origins

See .env.example for a template.

API Documentation

POST /mcp

Main MCP protocol endpoint. Accepts JSON-RPC 2.0 messages.

Request:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "browser_navigate", "arguments": { "url": "https://example.com" } } }

Response:

{ "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "Navigation completed" } ], "isError": false } }

GET /health

Health check endpoint. Returns service status.

Response:

{ "status": "healthy", "version": "1.0.0", "uptime": 3600, "timestamp": "2024-12-01T12:00:00.000Z" }

GET /

Service information endpoint.

Response:

{ "name": "Playwright MCP HTTP Server", "version": "1.0.0", "protocol": "MCP v0.1", "endpoints": { "mcp": "/mcp", "health": "/health" } }

Supported MCP Methods

The server supports all standard MCP methods:

initialize - Initialize MCP connection
initialized - Confirm initialization
tools/list - List available Playwright tools
tools/call - Invoke a Playwright tool

Available Playwright Tools

All tools from @playwright/mcp are supported:

browser_navigate - Navigate to a URL
browser_snapshot - Get accessibility snapshot
browser_take_screenshot - Capture screenshot
browser_click - Click an element
browser_type - Type text
browser_fill_form - Fill form fields
browser_evaluate - Execute JavaScript
browser_wait_for - Wait for conditions
browser_close - Close browser/page

For detailed tool parameters, see the Playwright MCP documentation.

Using the Server

Start locally with npm install, build (npm run build), then run npm start (or use npm run dev for auto-reload during development).
Call /, /health, or /mcp via curl/Postman/Playwright MCP clients; the /mcp endpoint accepts JSON-RPC POST requests (see the example below).
Adjust behavior by editing .env or setting env vars such as PORT, PLAYWRIGHT_BROWSER, and PLAYWRIGHT_HEADLESS.
Alternatively, containerize the service with docker build -t playwright-mcp-http-server . and docker run -p 8931:8931 ... for consistent deployments.

Updating the GitHub Repository

Pull the latest changes before making edits: git pull --rebase origin main.
Use git status to see touched files, then stage with git add <files> and commit with a descriptive message.
Push your branch with git push origin HEAD and open a pull request if the change needs review.

Example Usage

Using curl

# List available tools curl -X POST http://localhost:8931/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }' # Navigate to a page curl -X POST http://localhost:8931/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "browser_navigate", "arguments": { "url": "https://example.com" } } }' # Take a screenshot curl -X POST http://localhost:8931/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "browser_take_screenshot", "arguments": { "fullPage": true } } }'

Using JavaScript/TypeScript

// Use the live production instance or replace with your own deployment URL const MCP_SERVER_URL = 'https://playwright-mcp-http-server-554655392699.us-central1.run.app/mcp'; async function callPlaywrightMCP(method: string, params?: any) { const response = await fetch(MCP_SERVER_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: Date.now(), method, params, }), }); return response.json(); } // List tools const tools = await callPlaywrightMCP('tools/list'); // Navigate await callPlaywrightMCP('tools/call', { name: 'browser_navigate', arguments: { url: 'https://example.com' }, }); // Take screenshot const screenshot = await callPlaywrightMCP('tools/call', { name: 'browser_take_screenshot', arguments: { fullPage: true }, });

Note: The /mcp endpoint requires POST requests with JSON-RPC 2.0 formatted messages. GET requests will return a 404 error.

Deployment

Railway

Create a new Railway project
Connect your Git repository
Railway will auto-detect Node.js and use npm start
Set environment variables if needed
Deploy!

The service will use Railway's $PORT environment variable automatically.

Render

Create a new Web Service on Render
Connect your Git repository
Build command: npm install && npm run build
Start command: npm start
Set environment variables if needed
Deploy!

Google Cloud Platform (Cloud Run)

See DEPLOY_GCP.md for detailed instructions.

Quick deploy:

# Set your project ID export GCP_PROJECT_ID="your-project-id" # Deploy (Linux/Mac) chmod +x deploy-gcp.sh && ./deploy-gcp.sh # Deploy (Windows PowerShell) .\deploy-gcp.ps1 -ProjectId "your-project-id"

Or manually:

PROJECT_ID="your-project-id" IMAGE="gcr.io/${PROJECT_ID}/playwright-mcp-http-server" docker build -t $IMAGE . docker push $IMAGE gcloud run deploy playwright-mcp-http-server \ --image $IMAGE \ --region us-central1 \ --platform managed \ --allow-unauthenticated \ --port 8931 \ --memory 2Gi \ --cpu 2

Fly.io

Install Fly CLI: curl -L https://fly.io/install.sh | sh
Login: fly auth login
Launch app: fly launch
Deploy: fly deploy

Docker

# Build the image docker build -t playwright-mcp-http-server . # Run the container docker run -p 8931:8931 playwright-mcp-http-server # With environment variables docker run -p 8931:8931 \ -e PORT=8931 \ -e PLAYWRIGHT_HEADLESS=true \ playwright-mcp-http-server

Docker Compose

version: '3.8' services: playwright-mcp: build: . ports: - "8931:8931" environment: - PORT=8931 - PLAYWRIGHT_HEADLESS=true healthcheck: test: ["CMD", "node", "-e", "require('http').get('http://localhost:8931/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"] interval: 30s timeout: 10s retries: 3 start_period: 40s

Architecture

The service works by:

HTTP Server (Express) receives JSON-RPC requests
MCP Handler processes the requests and routes them to Playwright
Playwright Process Manager spawns @playwright/mcp as a child process
STDIO Communication handles JSON-RPC messages via stdin/stdout
Response is formatted and returned via HTTP

This architecture allows the Playwright process to run independently while being accessible via HTTP.

Troubleshooting

Service won't start

Check that Node.js 18+ is installed: node --version
Verify dependencies are installed: npm install
Check logs for error messages

Playwright browser not found

The browser will be downloaded automatically on first run
For Docker, ensure system dependencies are installed (included in Dockerfile)
Check network connectivity for browser downloads

High memory usage

Consider setting MAX_SESSIONS to limit concurrent sessions
Ensure browser_close is called when done with a session
Monitor for memory leaks in long-running processes

Timeout errors

Increase request timeout if operations take longer than 30 seconds
Check network connectivity to target URLs
Verify Playwright process is not crashed

Development

Project Structure

playwright-mcp-http-server/ ├── src/ │ ├── server.ts # HTTP server setup │ ├── mcp-handler.ts # MCP protocol handler │ ├── playwright-process.ts # Playwright process management │ ├── config.ts # Configuration │ └── types/ │ └── mcp.ts # TypeScript types ├── dist/ # Compiled JavaScript (generated) ├── package.json ├── tsconfig.json ├── Dockerfile └── README.md

Building

npm run build

Running Tests

Note: Tests are not yet implemented but planned for future releases

License

MIT

References

Support

For issues and questions, please open an issue on the repository.

Playwright MCP HTTP Server

Features

Quick Start

Prerequisites

Installation

🚀 Live Production Instance

Development

Configuration

API Documentation

POST /mcp

GET /health

GET /

Supported MCP Methods

Available Playwright Tools

Using the Server

Updating the GitHub Repository

Example Usage

Using curl

Using JavaScript/TypeScript

Deployment

Railway

Render

Google Cloud Platform (Cloud Run)

Fly.io

Docker

Docker Compose

Architecture

Troubleshooting

Service won't start

Playwright browser not found

High memory usage

Timeout errors

Development

Project Structure

Building

Running Tests

License

References

Support

Resources

New MCP Servers

Latest Blog Posts

MCP directory API