# Playwright MCP

An MCP server that gives compatible clients structured control of a real Playwright browser for QA, scraping diagnostics, accessibility-minded inspection, and reproducible browser workflows.

## Architecture

Transport entrypoints are thin:

- `src/index.ts` starts MCP over stdio.
- `src/http.ts` starts MCP over Streamable HTTP.
- `src/server.ts` builds one `McpServer` and registers all tools.

Core services own browser state:

- `BrowserManager` serializes tool execution, launches browsers lazily, and manages contexts/pages.
- `TelemetryStore` captures console messages, page errors, failed requests, and recent network events.
- Tool modules register focused actions and depend only on the public browser/session APIs.

Tool groups:

- Browser/context/page lifecycle
- Navigation and waiting
- Interaction
- Inspection and screenshots
- Assertions
- Diagnostics, tracing, and storage

## Install

```bash
npm install
npm run install-browsers
npm run build
```

## Run

```bash
npm start
```

HTTP transport:

```bash
npm run start:http
```

Default HTTP endpoint: `http://127.0.0.1:8931/mcp`.

## Production Controls

Configuration is environment-driven:

- `PLAYWRIGHT_MCP_HTTP_TOKEN`: require `Authorization: Bearer <token>` for HTTP mode.
- `PLAYWRIGHT_MCP_HTTP_ALLOWED_ORIGINS`: comma-separated CORS allowlist.
- `PLAYWRIGHT_MCP_ALLOWED_ORIGINS`: comma-separated browser navigation allowlist.
- `PLAYWRIGHT_MCP_BLOCKED_ORIGINS`: comma-separated browser navigation blocklist.
- `PLAYWRIGHT_MCP_ALLOW_EVALUATE`: enable the dangerous `evaluate` tool. Default: `false`.
- `PLAYWRIGHT_MCP_ALLOW_DOWNLOADS`: enable download tools and accepting downloads. Default: `false`.
- `PLAYWRIGHT_MCP_ALLOW_UPLOADS`: enable upload tools. Default: `false`.
- `PLAYWRIGHT_MCP_ARTIFACT_DIR`: screenshots, traces, PDFs, downloads, and storage state directory. Default: `./artifacts`.
- `PLAYWRIGHT_MCP_MAX_CONTEXTS`: browser context cap. Default: `8`.
- `PLAYWRIGHT_MCP_MAX_PAGES`: page cap. Default: `32`.
- `PLAYWRIGHT_MCP_DEFAULT_TIMEOUT_MS`: default Playwright timeout. Default: `30000`.
- `PLAYWRIGHT_MCP_LOG_LEVEL`: `debug`, `info`, `warn`, or `error`.

HTTP mode should use `PLAYWRIGHT_MCP_HTTP_TOKEN` before binding to anything other than localhost.

## MCP client config

Examples are available in `examples/`:

- `claude_config.json`
- `cursor_mcp.json`
- `codex_config.toml`
- `cline_mcp_settings.json`
- `opencode_config.json`


## Development

```bash
npm run check
```