How to use Playwright MCP with Claude Code: Browser automation and proxy setup

Standard scraping and QA scripts often break the moment a website updates its layout or renames a CSS class. Connecting the playwright-mcp package to the Claude Code CLI solves that problem. Through the Model Context Protocol (MCP), the browser sends a clean text map of the page straight to the AI agent. You no longer hunt for CSS selectors manually or send heavy screenshots to a vision model. QA engineers, scraper developers, and analysts control Chromium, Firefox, WebKit, and Microsoft Edge directly from the terminal while routing traffic through proxies.

TL;DR: quick summary of the Claude Playwright MCP workflow

• How it works: the playwright-mcp package sends Claude Code a lightweight playwright mcp accessibility snapshot (browser_snapshot) instead of heavy images, cutting token usage by up to 80%.

• One-command setup: running claude mcp add playwright -- npx @playwright/mcp@latest registers the official playwright mcp server for a single folder, a shared team repository, or globally across your computer.

• Profile isolation: combining the --isolated flag with a --storage-state cookie file (or separate --user-data-dir folders) lets you run multiple browser windows in parallel without file lock errors.

• Proxy routing: passing --proxy-server and HTTP_PROXY inside .mcp.json routes browser traffic through mobile LTE/5G, static residential ISP, or rotating residential proxies.

• Pre-flight IP check: before launching your task, verify your IP reputation in the built-in Fraud Score checker inside your CyberYozh App dashboard.

👉 Explore the CyberYozh App proxy catalog by country and provider type

What does Playwright MCP do inside the browser

What does playwright mcp do differently from older browser tools? Legacy visual AI agents took full-screen images and clicked buttons using approximate X and Y pixel coordinates. Whenever a promo banner popped up or the responsive layout shifted, the click missed.

The official playwright mcp server from Microsoft (@playwright/mcp) reads the browser's accessibility tree instead of capturing pixels. Calling browser_snapshot returns a structured text map of every interactive element on the page. Each button, link, or input receives an exact reference tag - such as textbox "Search catalog" [ref=e5] or button "Apply filter" [ref=e12]. Taking a playwright mcp accessibility snapshot lets Claude Code pass ref=e5 straight into browser_type or browser_click without coordinate guesswork. The server also inspects background API traffic (browser_network_requests), reads console logs (browser_console_messages), switches tabs, and exports PDFs or screenshots (browser_pdf_save, browser_take_screenshot).

This workflow connects three stages of automated data collection. Standard web scraping downloads raw HTML code, screen scraping reads visual data rendered in the browser after JavaScript executes, and data parsing extracts structured fields into CSV, Excel, or JSON. With playwright-mcp, the agent reads the live DOM tree after JavaScript finishes rendering and extracts structured data right away.

👉 Explore proxy infrastructure for AI agents and browser automation on CyberYozh App

How to use Playwright MCP with Claude Code in your terminal

Before testing how to use playwright mcp with Claude Code on live websites, verify three prerequisites on your machine: Node.js 18 or newer (Node.js 20+ LTS recommended), an authenticated Claude Code CLI (@anthropic-ai/claude-code), and active proxy credentials to prevent rate limiting.

How to add Playwright MCP to Claude Code: three setup modes

You can add Playwright MCP to Claude Code with a single command using the --scope flag to set the configuration level: local (current folder), project (shared team repo), or user (global profile). Local folder settings always override project and global settings.

Run the commands below to check your installed versions, pre-cache the Chromium binary, and register the server:

# 1. Check installed Node.js and Claude Code versions
node --version
claude --version

# 2. Pre-install the package and Chromium browser
npx @playwright/mcp@latest --version
npx playwright install chromium

# 3. Register the server (choose one of the three options)
# Option A: Only for the currently open folder
claude mcp add playwright -- npx @playwright/mcp@latest

# Option B: Globally for all your projects on this computer
claude mcp add playwright --scope user -- npx @playwright/mcp@latest

# Option C: Create a shared .mcp.json file in the project root for your team
claude mcp add playwright --scope project -- npx @playwright/mcp@latest

# 4. Verify the list of connected MCP servers
claude mcp list

After running claude mcp add playwright, you can also install the community ExecuteAutomation build (@executeautomation/playwright-mcp-server) for viewport presets across 143 smartphone and desktop models. If you prefer to scrape websites through Claude AI without editing config files manually, our open-source Yozh Scraper on GitHub routes traffic through your CyberYozh App proxies automatically.

👉 Rent mobile LTE/5G proxies from $1.70/day with unlimited traffic

Setting up a Playwright MCP proxy configuration in .mcp.json

When a claude playwright mcp session checks localized ad landing pages, compares regional prices, or scrapes product catalogs, rapid requests from a single home or office IP trigger CAPTCHAs. Adding a playwright mcp proxy configuration inside .mcp.json (or ~/.claude.json) routes browser traffic through your target region:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest",
        "--browser",
        "chromium",
        "--isolated",
        "--proxy-server=http://proxy.cyberyozh.com:8080"
      ],
      "env": {
        "HTTP_PROXY": "http://username:password@proxy.cyberyozh.com:8080",
        "HTTPS_PROXY": "http://username:password@proxy.cyberyozh.com:8080",
        "PLAYWRIGHT_MCP_PING_TIMEOUT_MS": "15000"
      }
    }
  }
}

Note: The server address (proxy.cyberyozh.com), port (8080), username, and password above are placeholders. Replace them with the host, port, and login credentials from your proxy card in the CyberYozh App dashboard.

How to manage browser profiles, cookies, and proxy IP persistence

To prevent profile lock crashes during parallel runs and avoid unexpected session resets, keep two mechanics separate:

1. Where browser cookies and sessions are stored: by default, playwright-mcp saves cookies and site data in a single shared folder on disk. Opening a second Claude Code terminal against that same folder causes a lock error. To run multiple browsers in parallel, launch a playwright mcp isolated profile with the --isolated flag (creating a clean profile in memory) and inject saved login cookies via --storage-state=./auth.json. If you need a permanent disk profile instead of an in-memory playwright mcp isolated profile, assign a dedicated folder per project with --user-data-dir.

2. How your proxy IP stays consistent: cookies and proxy IPs operate independently. A static IP will not renew an expired cookie token, and saved cookies will not prevent a logout if your external IP changes mid-checkout. Also note a Chromium limitation: the --proxy-server flag accepts a username and password only over HTTP/HTTPS. Direct SOCKS5 connections in Chromium work only with passwordless IP whitelisting in your dashboard, while password-protected SOCKS5 requires a local proxifier.

👉 Choose rotating residential proxies from $4.00/GB with sticky sessions up to 24 hours

Which CyberYozh App proxies to choose for playwright-mcp

The right proxy line depends on your target websites and session duration. The CyberYozh App platform offers four options for browser automation:

• Mobile LTE/4G/5G proxies (from $1.70/day with unlimited traffic): run on physical modems and real carrier SIM cards. Because mobile networks use CGNAT, hundreds of everyday smartphone subscribers share a single carrier IP. Anti-fraud filters and search engines like Google are much less likely to restrict that address during multi-threaded search scraping or ad checks. Private plans let you rotate the IP via a dashboard link or REST API, while shared plans rotate on a 5- or 30-minute timer. Supports HTTP/HTTPS, SOCKS5, UDP, VPN/VLESS configs, and TCP/IP OS fingerprint switching. Since carrier cell towers periodically refresh IP leases on their own side, rent a daily plan first to test session length for multi-hour runs.

• Static residential ISP proxies (from $5.29/month with unlimited traffic): provide one dedicated home IP from a real internet service provider (ISP) for the entire rental period, with 99.9% uptime and HTTP/HTTPS and SOCKS5 support. Built for multi-week and multi-month sessions across client and brand projects, ad dashboards, admin panels, and online stores. Agencies bind one static ISP proxy to a dedicated browser profile folder (--user-data-dir) per client so sessions and cookies never mix.

• Rotating residential proxies (from $4.00/GB, 3 GB minimum; down to $2.50/GB at 100 GB): give you access to 100M+ residential IPs across 195+ countries. Includes free country, state/region, and city targeting, pre-assignment Advanced IP filtering, 99.9% uptime, and up to 99.99% request success rate. Run per-request rotation for catalog scraping or hold an IP for up to 24 hours with sticky sessions. Unused gigabytes roll over to the next billing month, and the Mass Credentials Generator and REST API streamline bulk setups.

• Datacenter (server) proxies (from $1.77/month): offer dedicated and shared IPv4/IPv6 channels with unlimited traffic on dedicated plans and 99.99% uptime for high-speed scraping of public pages, uptime monitoring, and API testing.

👉 Select unlimited-traffic proxies for web scraping and browser automation

Checking IP reputation via Fraud Score and fixing common errors

Before adding a proxy to your playwright-mcp config, check its IP in the built-in Fraud Score risk checker ($0.15 per IP check, or $19.00/month for 1,500 IP checks, 1,500 phone number checks, and 500 bank card checks - saving up to $600/month). The tool queries IPQualityScore (IPQS), CyberSource, ThreatMetrix, Stripe Radar, PerimeterX, and 118 OSINT blacklists, showing the ISP/ASN label, risk score, and Abuse Velocity status before you launch the browser.

To test the connection, launch the client with MCP_TIMEOUT=10000 claude so npx has enough time to download the package on first run. Type /mcp in the chat to confirm playwright shows a green connected status. In your first prompt, explicitly name the tool so Claude opens the browser instead of writing script code:

Use Playwright MCP: open https://app.cyberyozh.com/checkers/, read the page structure, and list the available checkers for verifying IP addresses, phone numbers, and cards.

If your automated tests cover SMS registration forms or checkout flows, you can rent virtual phone numbers for receiving SMS and issue virtual cards in the same CyberYozh App dashboard.

👉 Check IP reputation and Fraud Score before launching your browser

Getting started with browser automation in Claude Code

Combining playwright-mcp with Claude Code lets you control a real browser using plain text commands from your terminal: the agent opens pages, targets elements through the accessibility tree, and extracts data without brittle selectors. Pairing that setup with mobile LTE/5G, static ISP, or rotating residential proxies from CyberYozh App keeps your regional testing, storefront checks, and catalog scraping stable across any location.

👉 Rent virtual phone numbers for SMS verification when testing registration flows