MCP Server

MCP Server (AI Integration)

The framework includes a Model Context Protocol (MCP) server that exposes Playwright automation capabilities to AI assistants like Claude and GPT.

What is MCP?

MCP is an open standard that lets AI assistants interact with tools and data through a standardized interface. The Playwright MCP server exposes browser automation as tools the AI can call.

Quick Start

# Start MCP server (stdio mode — for AI assistant integration)
npm run mcp

# HTTP mode (for remote access)
npm run mcp:local

# Debug mode (headed browser)
npm run mcp:debug

Configuration

Variable	Default	Description
MCP_MODE	stdio	Transport: stdio or http
MCP_PORT	3100	HTTP server port
MCP_HOST	localhost	HTTP server host
MCP_HEADLESS	true	Run browser headless
MCP_BROWSER	chromium	Browser: chromium, firefox, webkit
MCP_OUTPUT_DIR	./mcp-output	Output directory for traces/screenshots
MCP_SAVE_SESSION	false	Persist browser session to disk
MCP_CAPABILITIES	core,network,storage,vision	Enabled tool categories

Capabilities

Capability	Purpose
core	Navigate, click, fill, select, hover, scroll
network	Inspect requests, responses, network logs
storage	Cookies, localStorage, sessionStorage
vision	Coordinate-based interactions, screenshots
pdf	PDF generation from pages
devtools	Chrome DevTools Protocol (chromium only)

Example Workflows

Login Automation

npm run mcp:example:login

Automates login to SauceDemo, captures a screenshot, extracts the page snapshot, and saves auth state for reuse.

Locator Inspection

npm run mcp:example:locator

Inspects multiple locators on the login page and reports their existence, visibility, count, tag name, text content, attributes, and bounding box.

Trace Debugging

npm run mcp:example:trace

Records a Playwright trace of the login flow, then saves it for viewing with npx playwright show-trace.

Integration with AI Assistants

1. Start the MCP server: npm run mcp
2. Configure your AI assistant to connect via stdio or HTTP
3. The AI can control the browser, inspect pages, capture traces, and more

Project Structure

mcp/
├── config.ts             # Environment-based configuration
├── mcp-server.ts         # Main MCP server entry point
├── session-manager.ts    # Browser session lifecycle
├── trace-collector.ts    # Trace capture utilities
├── screenshot-capture.ts # Screenshot utilities
├── page-snapshot.ts      # Page structure extraction
├── locator-debugger.ts   # Locator inspection
├── auth-reuse.ts         # Auth state persistence
├── index.ts              # Public exports
└── examples/
    ├── login-automation.ts
    ├── locator-inspection.ts
    └── trace-debugging.ts

Troubleshooting

Issue	Solution
Server won't start	Run npm install, check Node.js >= 22
Browser not found	Run npx playwright install chromium
Port in use	Set MCP_PORT to a different port
AI not connecting	Verify transport mode matches (stdio vs HTTP)
Need headed debugging	Set MCP_HEADLESS=false