@executeautomation/playwright-mcp-server

Exposes Playwright browser automation capabilities through the Model Context Protocol, allowing Claude and other MCP-compatible clients to control headless and headed browsers (Chromium, Firefox, WebKit) by translating natural language instructions into Playwright API calls. The server acts as a bridge between LLM reasoning and browser control, handling session management, context switching, and command serialization across the MCP transport layer.

Provides MCP tools to navigate to URLs, handle page loads, manage browser history (back/forward), and wait for navigation events. The implementation wraps Playwright's navigation APIs (page.goto, page.goBack, page.goForward) with timeout handling, load state detection, and error propagation back to the LLM client, enabling reliable multi-step web workflows.

Implements the Model Context Protocol transport layer, handling JSON-RPC message serialization, tool registration, request/response routing, and client communication. Manages the MCP server lifecycle, tool discovery, and protocol compliance, enabling seamless integration with MCP-compatible clients (Claude Desktop, Cline, custom hosts) without requiring application-level protocol handling.

Enables CSS selector and XPath-based element discovery on the current page, returning element metadata (text content, attributes, bounding box, visibility state) without interaction. Uses Playwright's locator API under the hood with support for complex selectors, shadow DOM traversal, and element filtering by visibility/enabled state, allowing LLMs to inspect page structure before taking action.

Simulates user interactions (click, type, select, check/uncheck, drag-and-drop, keyboard shortcuts) on page elements using Playwright's action APIs. Handles element waiting, focus management, and input validation, translating high-level interaction intents from the LLM into low-level browser events with proper event sequencing and timing.

Extracts and analyzes page content including text, HTML, structured data, and page metadata. Supports full-page text extraction, HTML snapshot capture, JSON-LD/microdata parsing, and custom JavaScript evaluation for dynamic content extraction. Results are returned as structured data suitable for LLM processing and downstream analysis.

Captures visual snapshots of the current page or specific elements as PNG/JPEG images, with options for full-page capture, viewport-only capture, and element-specific screenshots. Images are returned as base64-encoded data or file paths, enabling visual feedback to LLMs and downstream vision models for page analysis and verification.

Executes arbitrary JavaScript code within the page context using Playwright's evaluate() API, enabling dynamic content extraction, page state manipulation, and custom logic execution. Code runs in the browser's JavaScript environment with access to the DOM, window object, and page-specific libraries, with results serialized back to the LLM as JSON.

Manages browser instances, pages, and contexts (isolated browser sessions with separate cookies, storage, and cache). Supports creating/closing browsers, managing multiple pages within a context, switching between contexts, and persisting/restoring browser state. Enables multi-user or multi-scenario automation workflows with isolated session management.

Provides tools for waiting on page conditions (element visibility, network idle, specific text appearance, custom conditions) with configurable timeouts and polling intervals. Enables reliable synchronization between LLM actions and page state changes, preventing race conditions and flaky automation by allowing explicit waits before proceeding with subsequent actions.

Implements error detection, logging, and recovery mechanisms for automation failures. Captures error context (stack traces, page state, screenshots), provides detailed error messages to LLMs, and supports retry logic with exponential backoff. Enables LLMs to reason about failures and attempt recovery without manual intervention.