# Playwright MCP

<div align="center">
  <img src="assets/playwright-logo.png" alt="Playwright Logo" width="200">
</div>

A Model Context Protocol (MCP) server that provides browser automation capabilities using [Playwright](https://playwright.dev). Enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models.

## Features

- **Fast and lightweight** - Uses Playwright's accessibility tree, not pixel-based input
- **LLM-friendly** - No vision models needed, operates purely on structured data
- **Deterministic** - Avoids ambiguity common with screenshot-based approaches

## Requirements

- Node.js 18 or newer
- Any MCP client (VS Code, Cursor, Claude Desktop, Windsurf, etc.)

## Quick Start

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["playwright-mcp@latest"]
    }
  }
}
```

### VS Code / Cursor

Go to Settings → MCP → Add Server and configure manually using the standard config above.

## Configuration

### Basic Options

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "playwright-mcp@latest",
        "--headless",              // Run browser in headless mode
        "--browser", "chromium",    // Choose browser: chromium, firefox, webkit
        "--viewport-size", "1280x720" // Set viewport size
      ]
    }
  }
}
```

### Browser Extension (Connect to Existing Browser)

Connect to your existing Chrome/Edge browser with logged-in sessions:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["playwright-mcp@latest", "--extension"]
    }
  }
}
```

See [extension/README.md](extension/README.md) for extension installation.

### Isolated Sessions

Run each session in an isolated browser context:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "playwright-mcp@latest",
        "--isolated",
        "--storage-state", "path/to/storage.json"
      ]
    }
  }
}
```

## Common Use Cases

### Web Scraping
Navigate to pages, extract data, take screenshots, and interact with forms.

### Testing & Automation
Verify elements, fill forms, click buttons, and run automated workflows.

### Browser Extension Integration
Connect to your existing browser to interact with pages where you're already logged in.

## Available Tools

- **Navigation**: `browser_navigate`, `browser_navigate_back`
- **Interaction**: `browser_click`, `browser_type`, `browser_fill_form`, `browser_select_option`
- **Inspection**: `browser_snapshot`, `browser_take_screenshot`, `browser_evaluate`
- **Tab Management**: `browser_tabs` (list, create, close, select)
- **Network**: `browser_network_requests`, `browser_console_messages`
- **Advanced**: PDF generation, coordinate-based interactions, test assertions

Run `npx playwright-mcp@latest --help` for full list of options.

## Documentation

- [Browser Extension Setup](extension/README.md)
- [MCP Documentation](https://modelcontextprotocol.io)

## License

MIT