Playwright MCP Server for Automation and Web Scraping

Overview

The Playwright MCP Server (mcp-playwright) exposes Playwright-powered browser automation as a Model Context Protocol (MCP) service. It lets external agents, LLM-based systems, or other services send structured requests to create browser sessions, navigate pages, run interactions, extract content, and capture screenshots or PDFs — all over a simple HTTP interface. By separating browser execution into a dedicated MCP server, you get scalable, language-agnostic automation that is easy to integrate into pipelines and LLM toolchains.

This server is useful when you need reliable, repeatable browser automation for web scraping, end-to-end testing, visual capture, or as an action tool for an AI agent. Running Playwright in a centralized service simplifies resource management (pooling, headless vs. headed execution), isolation of browser contexts, and operational concerns such as logging, timeouts, and browser lifecycle control.

Features

• Playwright-driven browser sessions (Chromium/Firefox/WebKit)
• Exposed via a simple HTTP/JSON MCP-compatible API
• Session lifecycle: create, reuse, and close browser contexts
• Common browser actions: goto, click, fill, evaluate, screenshot, pdf, get HTML, and cookies
• Support for headless and headed modes, configurable via environment variables
• Concurrency and pooling controls to scale safely in production
• Docker-friendly image for quick deployment
• Request-level timeouts and error handling suitable for scraping and automation

Installation / Configuration

Minimum requirements: Node.js (recommended LTS), Playwright browsers installed (or use the Docker image which includes browsers).

Install from source (Node.js project):

# Clone repo
git clone https://github.com/executeautomation/mcp-playwright.git
cd mcp-playwright

# Install dependencies and Playwright browsers
npm install
npx playwright install

Run locally:

# Start server with default env
PORT=3000 node dist/index.js

Run with Docker:

# Build and run (if you want to build locally)
docker build -t mcp-playwright .
docker run -p 3000:3000 -e PORT=3000 mcp-playwright

# Or pull an image if published
docker run -p 3000:3000 executeautomation/mcp-playwright:latest

Common environment variables:

Adjust these in your deployment environment or Docker Compose file.

Available Tools / Resources

This server exposes a set of high-level browser tools (examples). The exact tool names may vary; treat these as representative capabilities you can call via the MCP/HTTP API.

• open_session / new_context — create a browser context / session
• goto — navigate to a URL
• click — click an element (CSS selector)
• fill — fill an input field
• evaluate — run arbitrary JS in page context and return result
• html / content — get page HTML
• screenshot — capture full page or viewport screenshot (PNG)
• pdf — generate a PDF (Chromium only)
• cookies / set_cookies — read or set cookies
• close_session — close context and free resources
• list_sessions — list active sessions and metadata

Each tool typically accepts JSON arguments (selectors, options, timeouts) and returns structured JSON with success / error and data (base64 for images).

Example Requests

Simple curl example to navigate and get HTML:

curl -X POST http://localhost:3000/mcp/run \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "goto_and_html",
    "args": {
      "url": "https://example.com",
      "waitUntil": "networkidle"
    }
  }'

Node.js example using fetch to take a screenshot:

const res = await fetch('http://localhost:3000/mcp/run', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tool: 'screenshot',
    args: {
      url: 'https://news.example',
      fullPage: true,
      format: 'png'
    }
  })
});
const json = await res.json();
const imageBase64 = json.data.image; // decode and save

Adjust tool names and payloads to match the server’s API details in the repository documentation.

Use Cases

• Web scraping dynamic sites: load pages that rely on JavaScript, wait for content to render, and extract structured data (tables, product details, or JSON embedded in the page).
• LLM tool for browsing: provide an LLM with the ability to browse pages, click links, take screenshots, and extract text using the MCP interface.
• Visual regression and screenshots: produce consistent screenshots or PDFs of pages for archiving or visual QA.
• Form automation and testing: fill forms, submit them, and assert resulting page content or status codes as part of end-to-end tests.
• Cookie/session management: authenticate in a browser context, save cookies, and reuse session state across requests for authenticated scraping.

Next Steps

• Review the repository README and API docs for exact endpoints, request schemas, and authentication options.
• Run the server in a local Docker container for quick experimentation.
• Integrate with your agent or orchestration layer by calling the MCP endpoints for browser actions, and implement retries, rate limits, and result caching on the client side for robust scraping pipelines.

Repository: https://github.com/executeautomation/mcp-playwright