# Browser Automation Agent with Playwright MCP

> Give an MCP client a Playwright-powered browser so the agent can navigate, click, and fill forms using accessibility snapshots instead of screenshots.

Category: MCP & Tool Use  
Tags: playwright, mcp, browser, automation, accessibility  
Setup time (estimate): 15-45 minutes  
Estimated cost: Free open-source MCP server (@playwright/mcp); you pay only your LLM provider for the agent that drives it, plus any browser/CI hosting.  
Last verified: 2026-10-15

Microsoft's Playwright MCP server exposes browser tools over the Model Context Protocol. The agent works from structured accessibility snapshots (roles, names, refs), so you do not need a vision model for ordinary UI work.

## Prerequisites

- Node.js 20 or newer (Playwright docs; npm package notes Node 18+)
- An MCP client: Claude Desktop, Cursor, VS Code, or another MCP-capable host

## Claude Desktop / standard MCP config

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

Headless or another browser:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--browser=firefox"]
    }
  }
}
```

Supported `--browser` values: `chrome`, `firefox`, `webkit`, `msedge`.

## Steps

### Step 1 — Add the config and restart

Add the config above to your MCP client and restart the client.

### Step 2 — Ask the agent to browse

Ask the agent to open a page and act, for example: navigate to `https://demo.playwright.dev/todomvc` and add a few todos.

### Step 3 — Work from accessibility refs

The server returns accessibility snapshots with element refs (such as `ref=e5`); the model clicks and types against those refs.

### Step 4 — Headless / CI via HTTP

For CI or headless workers without a display, either pass `--headless`, or run a standalone HTTP server and point the client at it:

```bash
npx @playwright/mcp@latest --port 8931
```

Client config then uses `"url": "http://localhost:8931/mcp"` instead of `command`/`args`.

### Step 5 — Advanced config file

For advanced options (viewport, network rules, timeouts), use `npx @playwright/mcp@latest --config path/to/config.json`.

## Notes

- Default mode is headed so you can watch the browser; pass `--headless` in automation.
- Persistent profile is the default (cookies kept). Use `--isolated` for a clean session each time.
- The `browser_run_code_unsafe` tool runs arbitrary Playwright JavaScript in the server process (RCE-equivalent); only enable it for trusted clients.
- Package verified on npm as `@playwright/mcp` (0.0.83 as of check); prefer `@latest` in config so clients pick up fixes.

## Sources (official docs, checked 2026-10-15)

- [Playwright MCP getting started](https://playwright.dev/docs/getting-started-mcp)
- [Playwright MCP configuration options](https://playwright.dev/mcp/configuration/options)
- [microsoft/playwright-mcp on GitHub](https://github.com/microsoft/playwright-mcp)
- [npm @playwright/mcp](https://www.npmjs.com/package/@playwright/mcp)

## Failure modes

- Pages that rely on canvas or heavily visual UI give weak accessibility snapshots; the agent may need a screenshot tool or computer-use path instead.
- browser_run_code_unsafe is RCE-equivalent; only enable it for trusted MCP clients.
- Headed browsers in headless CI/IDE workers need DISPLAY or --port HTTP transport; otherwise the server fails to start.
- Persistent profiles keep cookies between sessions; use --isolated or a dedicated --user-data-dir when you need a clean login state.