Skip to main content
Glama
Skeleton MCP Server

Skeleton MCP Server

by nickweedon

Playwright MCP Proxy

A proxy server for Microsoft's playwright-mcp that provides efficient handling of large binary data (screenshots, PDFs) through blob storage and supports browser pools for concurrent operations.

Version 2.0.0: Now with browser pools! Run multiple isolated browser instances with different configurations simultaneously.

Features

  • Browser Pools: Multiple isolated browser instances organized into named pools with different configurations

  • Concurrent Operations: Lease browser instances for exclusive use, enabling parallel browser automation

  • Playwright Browser Automation: Full access to all playwright-mcp browser automation tools

  • Stealth Mode: Built-in anti-detection capabilities (see STEALTH.md)

  • Efficient Binary Handling: Large screenshots and PDFs automatically stored as blobs to reduce token usage

  • Blob Storage: Built-in blob management using mcp-mapped-resource-lib

  • Automatic Cleanup: TTL-based automatic expiration of old blobs

  • Docker Support: Containerized deployment with multi-runtime support (Python + Node.js + Playwright)

  • Health Monitoring: Real-time pool status and instance health checks

Related MCP server: MCP Server Template

Quick Start

Prerequisites

  • Python 3.10 or higher

  • Node.js 18+ (for playwright-mcp)

  • uv package manager (recommended)

  • Docker (optional, for containerized deployment)

Installation

  1. Clone this repository:

git clone <this-repo> playwright-proxy-mcp
cd playwright-proxy-mcp
  1. Install dependencies:

uv sync
  1. Create your environment file:

cp .env.example.single-pool .env
# Edit .env with your configuration
  1. Run the server:

uv run playwright-proxy-mcp

The server will:

  • Start the playwright-mcp subprocess(es) via npx

  • Initialize blob storage

  • Initialize browser pools

  • Listen for MCP client connections on stdio

Browser Pools

Overview

Browser pools allow you to run multiple browser instances with different configurations:

# Global defaults (apply to all pools)
PW_MCP_PROXY_BROWSER=chromium
PW_MCP_PROXY_HEADLESS=true

# Define a pool with 3 instances
PW_MCP_PROXY__DEFAULT_INSTANCES=3
PW_MCP_PROXY__DEFAULT_IS_DEFAULT=true
PW_MCP_PROXY__DEFAULT_DESCRIPTION="General purpose browsing"

# Instance-level overrides
PW_MCP_PROXY__DEFAULT__0_BROWSER=firefox      # Instance 0 uses Firefox
PW_MCP_PROXY__DEFAULT__1_ALIAS=debug          # Instance 1 has alias "debug"
PW_MCP_PROXY__DEFAULT__1_HEADLESS=false       # Instance 1 runs headed

Using Pools

All browser tools accept optional browser_pool and browser_instance parameters:

# Use default pool, FIFO instance selection
await browser_navigate(url="https://example.com")

# Use specific pool
await browser_navigate(url="https://example.com", browser_pool="FIREFOX")

# Use specific instance by alias
await browser_navigate(url="https://example.com", browser_instance="debug")

Monitoring Pools

# Get status of all pools
status = await browser_pool_status()
for pool in status["pools"]:
    print(f"{pool['name']}: {pool['available_instances']}/{pool['total_instances']} available")

See docs/BROWSER_POOLS_SPEC.md for complete configuration reference.

Docker Deployment

Build and run with Docker Compose:

docker compose up -d

This will:

  • Build a container with Python, Node.js, and Playwright browsers

  • Create persistent volumes for blob storage and playwright output

  • Start the proxy server

Configuration

Configure the proxy via environment variables in .env:

Global Browser Settings

  • PW_MCP_PROXY_BROWSER: Browser to use (chromium, firefox, webkit) - default: chromium

  • PW_MCP_PROXY_HEADLESS: Run headless - default: true

  • PW_MCP_PROXY_CAPS: Capabilities (vision,pdf,testing,tracing) - default: vision,pdf

  • PW_MCP_PROXY_TIMEOUT_ACTION: Action timeout in ms - default: 15000

  • PW_MCP_PROXY_TIMEOUT_NAVIGATION: Navigation timeout in ms - default: 30000

Pool Configuration

  • PW_MCP_PROXY__<POOL>_INSTANCES: Number of instances in pool

  • PW_MCP_PROXY__<POOL>_IS_DEFAULT: Mark as default pool

  • PW_MCP_PROXY__<POOL>_DESCRIPTION: Pool description

  • PW_MCP_PROXY__<POOL>__<ID>_BROWSER: Browser for specific instance

  • PW_MCP_PROXY__<POOL>__<ID>_ALIAS: Alias for specific instance

  • PW_MCP_PROXY__<POOL>__<ID>_HEADLESS: Headless mode for specific instance

Stealth Settings (Anti-Detection)

  • PW_MCP_PROXY_ENABLE_STEALTH: Quick enable - Auto-configure stealth settings - default: false

  • PW_MCP_PROXY_USER_AGENT: Custom user agent string - optional

  • PW_MCP_PROXY_INIT_SCRIPT: Path to custom init script - optional

  • PW_MCP_PROXY_IGNORE_HTTPS_ERRORS: Ignore HTTPS errors - default: false

Tip: Simply set PW_MCP_PROXY_ENABLE_STEALTH=true to automatically enable anti-detection features!

See docs/STEALTH.md for detailed stealth configuration.

Blob Storage Settings

  • BLOB_STORAGE_ROOT: Storage directory - default: /mnt/blob-storage

  • BLOB_MAX_SIZE_MB: Max size per blob - default: 500

  • BLOB_TTL_HOURS: Time-to-live for blobs - default: 24

  • BLOB_SIZE_THRESHOLD_KB: Size threshold for blob storage - default: 50

  • BLOB_CLEANUP_INTERVAL_MINUTES: Cleanup frequency - default: 60

See example env files in the repository root for complete configuration examples.

How It Works

Binary Data Interception

The proxy automatically detects large binary data in playwright tool responses:

  1. When playwright tools return screenshots or PDFs

  2. If the data size exceeds the threshold (default: 50KB)

  3. The proxy stores the binary data as a blob

  4. The response is transformed to include a blob reference instead

Before (direct playwright-mcp):

{
  "screenshot": "data:image/png;base64,iVBORw0KGgo...500KB of data..."
}

After (through proxy):

{
  "screenshot": "blob://1733577600-a3f2c1d9e4b5.png",
  "screenshot_size_kb": 500,
  "screenshot_mime_type": "image/png",
  "screenshot_expires_at": "2024-12-08T10:00:00Z"
}

Retrieving Blobs

Blob retrieval is handled by a separate MCP Resource Server. See mcp-mapped-resource-lib for details.

Available Tools

Browser Tools

All playwright-mcp tools are available with browser pool support:

  • browser_navigate: Navigate to a URL

  • browser_click: Click an element

  • browser_fill: Fill a form field

  • browser_screenshot: Take a screenshot (auto-stored as blob if large)

  • browser_snapshot: Get ARIA snapshot

  • browser_evaluate: Execute JavaScript

  • And 40+ more tools...

All tools accept optional browser_pool and browser_instance parameters.

Pool Management

  • browser_pool_status(pool_name): Get pool health, lease activity, and instance status

Architecture

┌─────────────────────────────────┐
│  MCP Client (Claude Desktop)   │
└────────────┬────────────────────┘
             │ stdio
┌────────────▼────────────────────┐
│  FastMCP Proxy (Python)         │
│  - Pool Manager                 │
│  - Binary Interception          │
│  - Blob Storage Integration     │
│  - Instance Leasing (FIFO)      │
└────────────┬────────────────────┘
             │ stdio (per instance)
┌────────────▼────────────────────┐
│  playwright-mcp instances       │
│  - Browser Automation           │
│  - Screenshot/PDF Generation    │
└─────────────────────────────────┘

Testing

Run the test suite:

uv run pytest -v

Lint the code:

uv run ruff check src/ tests/
uv run ruff format src/ tests/

Project Structure

src/playwright_proxy_mcp/
├── server.py              # Main MCP proxy server
├── types.py               # TypedDict definitions
├── playwright/            # Playwright proxy components
│   ├── config.py         # Configuration loading (pool config)
│   ├── pool_manager.py   # Browser pool management
│   ├── process_manager.py # Subprocess management
│   ├── blob_manager.py   # Blob storage wrapper
│   ├── middleware.py     # Binary interception
│   └── proxy_client.py   # Stdio transport integration
└── utils/
    ├── navigation_cache.py     # TTL-based pagination cache
    ├── aria_processor.py       # ARIA snapshot processing
    └── jmespath_extensions.py  # Custom JMESPath functions

Benefits

Token Savings

Large screenshots can consume 50,000+ tokens. With blob storage:

  • Screenshots stored as blobs use ~100 tokens for the reference

  • Retrieve full data only when needed

  • Automatic cleanup prevents storage bloat

Concurrent Operations

Browser pools enable:

  • Parallel browser automation

  • Instance isolation for concurrent tasks

  • Different browser configurations for different use cases

Performance

  • Faster response times for tool calls

  • Reduced context window usage

  • Efficient deduplication of identical screenshots

  • FIFO instance leasing for fair resource allocation

Troubleshooting

npx not found

Ensure Node.js is installed and npx is in your PATH:

node --version
npx --version

Playwright browser installation fails

Install browsers manually:

npx playwright@latest install chromium --with-deps

Blob storage permissions

Ensure the blob storage directory is writable:

chmod -R 755 /mnt/blob-storage

Pool not starting

Check the pool configuration in your .env file. Ensure:

  • At least one pool has IS_DEFAULT=true

  • Instance counts are valid (positive integers)

  • No alias conflicts with numeric instance IDs

License

MIT

Contributing

Contributions welcome! Please open an issue or pull request.

Resources

Available Tools

6 tools
create_itemB

Create a new item.

Args: name: The name of the item (required) description: Optional description metadata: Optional key-value metadata

Returns: The created item data including the generated ID

Inputs: name (required), description, metadata. Returns: object

delete_itemC

Delete an item.

Args: item_id: The unique identifier of the item to delete

Returns: A confirmation message

Raises: ValueError: If the item is not found

Inputs: item_id (required). Returns: object

get_itemA

Get a specific item by ID.

Args: item_id: The unique identifier of the item

Returns: The item data if found

Raises: ValueError: If the item is not found

Inputs: item_id (required). Returns: object

health_checkB

Check the health status of the MCP server.

Returns: A dictionary with the server status and configuration info.

Inputs: no named parameters. Returns: object

list_itemsA

List all items with optional filtering and pagination.

Args: page: Page number (1-indexed) page_size: Number of items per page filter_name: Optional filter by name (case-insensitive contains)

Returns: A dictionary containing: - items: List of item objects - total: Total number of items matching the filter - page: Current page number - page_size: Number of items per page

Inputs: page, page_size, filter_name. Returns: object

update_itemB

Update an existing item.

Args: item_id: The unique identifier of the item to update name: New name (optional) description: New description (optional) metadata: New metadata (optional, replaces existing)

Returns: The updated item data

Raises: ValueError: If the item is not found

Inputs: item_id (required), name, description, metadata. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: create_item, delete_item, get_item, list_items, and update_item form a complete CRUD set for items, while health_check is a separate server management tool. The descriptions reinforce distinct actions on specific resources, eliminating any ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case throughout: create_item, delete_item, get_item, health_check, list_items, update_item. The naming is predictable and readable, with no deviations in style or convention.

    Tool Count5/5

    With 6 tools, this server is well-scoped for managing items and checking server health. The count is appropriate, providing full CRUD operations plus a utility tool without being overly complex or insufficient for the domain.

    Completeness5/5

    The tool surface is complete for the item management domain, covering create, read (get and list), update, and delete operations with proper pagination and filtering. The health_check tool adds server monitoring, leaving no obvious gaps for core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive template for building Model Context Protocol servers with FastMCP framework, featuring modular architecture, auto-discovery registry, and support for multiple transport methods. Includes example arithmetic and weather tools to help developers quickly create custom MCP servers.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A minimal, dockerized template for creating HTTP-based Model Context Protocol servers. Provides a starting point with FastMCP framework integration and includes a sample cat fact tool that can be replaced with custom functionality.
      -
    • A
      license
      A
      quality
      D
      maintenance
      A template project for building Model Context Protocol servers with FastMCP framework, Docker support, and example CRUD API implementation to help developers quickly bootstrap their own MCP servers.
      6
      MIT