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.

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

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

Headless or another browser:

{
  "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:

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
• Playwright MCP configuration options
• microsoft/playwright-mcp on GitHub
• npm @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.

Markdown version: /blueprints/browser-automation-agent.md

Related blueprints