Claude Code + Playwright MCP

Claude Code connects to a Browserless cloud browser over CDP using Microsoft's official Playwright MCP server, giving your AI agent managed infrastructure with anti-detection, residential proxies, and automatic CAPTCHA solving — no local browser required.

Prerequisites

• A Browserless API token (available in your account dashboard)
• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Node.js 18 or later (required by the Playwright MCP server)

Quick start

Register the Playwright MCP server and point it at your Browserless endpoint:

claude mcp add playwright-browserless \
  -- npx -y @playwright/mcp@latest \
  --cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true"

That single command does three things:

1. Registers Microsoft's official @playwright/mcp server with Claude Code
2. Routes all browser traffic through Browserless's /stealth endpoint (anti-detection enabled)
3. Turns on automatic CAPTCHA solving at the infrastructure level

Start Claude Code and verify:

claude

Then try:

Use playwright to navigate to https://www.google.com and take a snapshot

tip

Say "playwright" explicitly in your first message. Claude Code sometimes defaults to running Playwright through bash commands if you don't mention it by name.

Connection URL anatomy

The CDP endpoint URL controls which Browserless features are active for the session:

wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true

Segment	Purpose
production-sfo.browserless.io	Regional endpoint (SFO). Also available: production-lon for EU, production-ams for Amsterdam
/stealth	Stealth route — hides automation signals, spoofs fingerprints, reduces bot detection
token=	Your Browserless API token
solveCaptchas=true	Automatically detects and solves CAPTCHAs in real time

Route options

Route	Use case
/stealth	Best for most AI agent workflows. Anti-detection enabled by default
/	Standard route. Use when stealth is not needed

Cloud browser without stealth or CAPTCHA solving

If you don't need anti-detection or automatic CAPTCHA solving and just want Browserless as managed cloud browser infrastructure, use the standard route and omit solveCaptchas:

claude mcp add playwright-browserless \
  -- npx -y @playwright/mcp@latest \
  --cdp-endpoint "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN"

You still get a fully managed, remote browser — just without the stealth fingerprinting and CAPTCHA solving layers.

Useful query parameters

Parameter	Example	Description
solveCaptchas	true	Auto-solve CAPTCHAs without any code changes
timeout	300000	Session timeout in ms (default 30 s, increase for long-running tasks)
proxy	residential	Route traffic through residential proxies for additional anti-detection
blockAds	true	Block ads and trackers for cleaner page loads

Combine them as needed:

claude mcp add playwright-browserless \
  -- npx -y @playwright/mcp@latest \
  --cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true&timeout=300000&proxy=residential"

How stealth mode works

The /stealth route automatically applies anti-detection techniques before your agent interacts with any page:

• Hides navigator.webdriver and other automation signals
• Spoofs browser fingerprints (canvas, WebGL, fonts)
• Randomizes user-agent strings
• Mimics human-like browser behavior patterns

No code or configuration changes needed — the stealth protections are applied at the browser level, transparently to Playwright and Claude Code.

When stealth alone isn't enough (some sites still trigger challenges), solveCaptchas=true provides the second layer of defense.

How automatic CAPTCHA solving works

With solveCaptchas=true in your connection URL, Browserless monitors every page for CAPTCHA challenges and solves them in the background. This happens entirely at the infrastructure layer — Playwright and Claude Code don't need to do anything.

The system:

1. Detects CAPTCHAs by monitoring network requests for known CAPTCHA service patterns (reCAPTCHA, hCaptcha, Cloudflare Turnstile, etc.)
2. Solves them programmatically using Browserless's solving engine
3. Fires CDP events (Browserless.captchaFound, Browserless.captchaAutoSolved) for monitoring

Since solving can take a few seconds to a minute, you'll want to give Claude Code guidance on how to handle this. See System prompt for Claude Code below.

note

Each CAPTCHA solve attempt costs 10 units. Using /stealth and residential proxies reduces how often CAPTCHAs appear in the first place.

System prompt for Claude Code

Claude Code doesn't inherently know that Browserless is handling CAPTCHAs and stealth in the background. Without guidance, it may try to interact with CAPTCHA elements directly or give up when it sees a challenge page.

Add this to your Claude Code system prompt (via CLAUDE.md in your project root, or passed via --system-prompt):

## Browser automation context

You are connected to a Browserless cloud browser via Playwright MCP. The browser
has stealth anti-detection and automatic CAPTCHA solving enabled at the
infrastructure level. Important behavior guidelines:

### CAPTCHA handling
- **Do NOT attempt to click, solve, or interact with CAPTCHA elements yourself.**
  CAPTCHAs (reCAPTCHA, hCaptcha, Cloudflare Turnstile, etc.) are solved
  automatically by the browser infrastructure.
- If you detect a CAPTCHA or challenge page, **wait 15-30 seconds**, then take a
  new snapshot to check if the page has updated.
- If the CAPTCHA is still present after 60 seconds, report it to the user rather
  than attempting to interact with it.

### Bot detection and blocking
- The browser is already running in stealth mode with anti-detection protections.
  You do not need to take any special steps to avoid detection.
- If a site blocks you or shows a "bot detected" page, wait 10 seconds and retry
  once. If still blocked, report it to the user.

### Session management
- The browser session has a timeout configured by the connection URL. For
  long-running tasks, be mindful of the session duration.
- Each `browser_navigate` call reuses the same browser context. Cookies and
  session state persist across navigations within the same session.

### Best practices
- Use `browser_snapshot` (accessibility tree) as your primary observation method.
  It's faster and more token-efficient than screenshots.
- Use `browser_take_screenshot` only when you need to verify visual layout or
  see something the accessibility tree doesn't capture.
- When filling forms, use `browser_type` for text inputs and `browser_click`
  for buttons and checkboxes.

Why this matters

Without this prompt, Claude Code will:

• See a CAPTCHA element in the accessibility snapshot and try to click it
• Report "I'm unable to proceed because there's a CAPTCHA" before auto-solve finishes
• Attempt its own "stealth" workarounds (modifying user-agent, etc.) that conflict with Browserless's stealth

With this prompt, Claude Code knows to wait and let the infrastructure handle it.

Example workflows

Web research with anti-detection

Navigate to https://www.g2.com/products/browserless/reviews and extract
the 5 most recent reviews. Get the reviewer name, rating, and summary
for each.

Claude Code will navigate via the stealth Browserless browser, handle any Cloudflare challenges automatically, and extract the data from the accessibility tree.

Form submission through CAPTCHA-protected pages

Go to https://example.com/contact, fill in the form with:
- Name: Test User
- Email: test@example.com
- Message: "I'd like to learn more about your enterprise plan"

Then submit the form.

If the form has a reCAPTCHA, Browserless solves it transparently before (or during) form submission.

Multi-step authenticated workflow

1. Navigate to https://app.example.com/login
2. Wait for me to log in manually
3. Once I confirm, navigate to the settings page and take a screenshot

Since Browserless maintains a persistent browser context, cookies and auth state carry through the entire session.

Configuration options

Per-project setup

Scope the MCP registration to a project so teammates get the same config:

claude mcp add --scope project playwright-browserless \
  -- npx -y @playwright/mcp@latest \
  --cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true"

This writes to .mcp.json in the project directory, which you can commit to version control (with token managed via environment variable).

Using environment variables for the token

Avoid committing tokens by using an environment variable:

export BROWSERLESS_TOKEN="your-api-token"

claude mcp add playwright-browserless \
  -- npx -y @playwright/mcp@latest \
  --cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=${BROWSERLESS_TOKEN}&solveCaptchas=true"

Increasing the session timeout

For tasks that take more than 30 seconds (the default), increase the timeout:

claude mcp add playwright-browserless \
  -- npx -y @playwright/mcp@latest \
  --cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true&timeout=300000"

timeout=300000 gives you 5 minutes. Adjust as needed for your workflow.

Adding residential proxies

For sites with aggressive geo-based blocking or IP reputation checks:

claude mcp add playwright-browserless \
  -- npx -y @playwright/mcp@latest \
  --cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true&proxy=residential"

See Proxy configuration for more options including country targeting and sticky sessions.

Troubleshooting

Claude Code tries to solve CAPTCHAs manually

Add the system prompt above to your CLAUDE.md. Without it, Claude sees CAPTCHA elements in the accessibility tree and tries to interact with them.

"Connection timeout" errors

The Playwright MCP server defaults to a 30-second CDP connection timeout. If Browserless is slow to provision a browser:

claude mcp add playwright-browserless \
  -- npx -y @playwright/mcp@latest \
  --cdp-endpoint "wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true" \
  --cdp-timeout 60000

Claude Code uses bash Playwright instead of MCP

Say "use Playwright MCP" explicitly in your first message. Claude Code defaults to writing and running Playwright scripts via bash if it doesn't know MCP is available. After the first interaction, it remembers.

CAPTCHA solving takes too long

Solving can take up to 60 seconds for complex challenges. If you're hitting timeouts:

1. Increase the session timeout (timeout=300000)
2. Add residential proxies (proxy=residential) to reduce CAPTCHA frequency
3. Use the /stealth route (not /) to prevent most CAPTCHAs from appearing

Site still detects the browser as a bot

Layer defenses:

1. Start with the /stealth route (included in the quick start)
2. Add proxy=residential for IP reputation
3. If still blocked, try the Site Unblocking API for the most aggressive anti-detection

Available Playwright MCP tools

Once connected, Claude Code has access to these browser automation tools:

Tool	Description
browser_navigate	Navigate to a URL
browser_snapshot	Capture the accessibility tree (primary observation method)
browser_click	Click an element by reference
browser_type	Type text into a form field
browser_take_screenshot	Capture a PNG screenshot
browser_go_back / browser_go_forward	Browser history navigation
browser_wait	Wait for a specified duration
browser_press_key	Press a keyboard key
browser_select_option	Select from a dropdown
browser_hover	Hover over an element
browser_drag	Drag and drop
browser_resize	Resize the browser viewport
browser_tab_*	Tab management (new, select, close, list)
browser_file_upload	Upload files to file inputs
browser_pdf_save	Save page as PDF

All of these tools execute against your Browserless cloud browser with stealth and CAPTCHA solving active.

Resources

• Stealth routes — deep dive on anti-detection techniques
• CAPTCHA solving — programmatic detection and solving via CDP
• Site unblocking — API for the most protected sites
• Session management — persistent sessions, reconnection, live URLs
• Hybrid automation — combine AI automation with human-in-the-loop
• Browserless Account Dashboard — get your API token
• AI Integrations — other AI platform integrations