auto-captcha — Universal Captcha Solver for Playwright

Drop-in captcha bypass for Playwright browser automation. Detects hCaptcha, reCAPTCHA v2/v3, and Cloudflare Turnstile, solves them via the NopeCHA Token API, and injects tokens automatically — so your automation scripts never stall.

Your script → page loads → captcha detected → NopeCHA API → token injected → continue

Quick Start

pip install auto-captcha
python -m playwright install chromium

from auto_captcha_solver import smart_page

with smart_page(api_key="your-nopecha-key") as page:
    page.goto("https://protected-site.com")
    page.fill("#email", "user@example.com")
    page.click("#submit")  # captcha auto-solved → form submits

Why This Exists

Browser automation hits captcha walls. Existing solutions either require manual intervention or brittle image-to-text heuristics. auto-captcha uses a commercial token API (NopeCHA) that actually solves the challenge server-side — it's the same API powering many production captcha-bypass automation tools.

Features:

• Automatic detection — scans frames and DOM for hCaptcha, reCAPTCHA v2/v3, Turnstile
• Zero-config wrapper — smart_page() context manager handles everything
• Fine-grained control — CaptchaSolver class exposes detect/solve/inject separately
• MCP server included — use from Claude Code, Cursor, or any MCP-compatible agent
• CLI tool — solve or detect from the command line
• Playwright CLI compatibility — works alongside playwright-cli workflows

Note: Requires a NopeCHA API key (free tier available). See https://nopecha.com

Installation

Core Package

pip install auto-captcha

With Playwright (recommended)

pip install auto-captcha[playwright]
python -m playwright install chromium

Or install separately:

pip install playwright
python -m playwright install

Three Ways to Use

1. smart_page() — Context Manager (easiest)

Manages browser lifecycle and auto-solves on navigation/click events.

from auto_captcha_solver import smart_page

with smart_page(api_key="your-key") as page:
    page.goto("https://example.com")
    page.fill("#email", "user@test.com")
    page.click("#submit")  # auto-solved
    print(page.captcha_log)  # [{'type': 'hcaptcha', 'status': 'solved'}]

Options:

• headless=False — see the browser
• wait_after_load=3.0 — delay before solving (site-dependent)

2. SmartPage — Wrap an Existing Page

Use when you already have a Playwright page/browser instance:

from auto_captcha_solver import SmartPage
from playwright.sync_api import sync_playwright

pw = sync_playwright().start()
browser = pw.chromium.launch(headless=True)
raw_page = browser.new_page()
page = SmartPage(raw_page, api_key="your-key")

page.goto("https://site.com")  # captchas auto-solved
page.fill("#input", "value")
page.click("#submit")
browser.close()
pw.stop()

3. CaptchaSolver — Full Control

Detect, solve, and inject manually:

from auto_captcha_solver import CaptchaSolver

solver = CaptchaSolver(api_key="your-key")

# Detect all captchas on the page
captchas = solver.detect(page)
# → [{'type': 'hcaptcha', 'sitekey': 'abc123', 'url': 'https://...'}]

# Solve one
result = solver.solve(captcha_type="hcaptcha", sitekey="abc123", url=page.url)
if result.success:
    # Inject into page
    solver.inject(page, "hcaptcha", result.token)

Stealth & Context Cloning

Token solves are minted server-side by the provider, so the token's context (IP, User-Agent, cookies) must match the browser that presents it — otherwise anti-bot systems (especially Cloudflare Turnstile) invalidate it on submit.

apply_stealth(context) masks the in-page fingerprint leaks a vanilla headless Chromium exposes (navigator.webdriver, missing window.chrome, empty navigator.plugins, SwiftShader WebGL vendor). Call it once on the BrowserContext, before creating pages:

from auto_captcha_solver import CaptchaSolver, apply_stealth
with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context()   # or use your real profile
    apply_stealth(context)            # mask fingerprint
    page = context.new_page()
    solver = CaptchaSolver(api_key="your-key")
    results = solver.auto_solve(page) # UA + cookies cloned automatically

clone_context(page) snapshots the browser's real User-Agent and cookies so you can forward them to solve():

from auto_captcha_solver import clone_context
ctx = clone_context(page)  # {"useragent": str|None, "cookies": list|None}
result = solver.solve("hcaptcha", sitekey, page.url, **ctx)

• auto_solve(..., clone_context=True) (default) forwards the live UA + cookies and reads data-action/data-cdata off the widget for reCAPTCHA v3 / Turnstile metadata.
• Turnstile requires a proxy whose IP matches the client's — solve() emits a warning if you call it without proxy=....
• The Runtime.enable CDP leak (below the JS layer) is closed only by driving the browser with Patchright — a drop-in Playwright fork. apply_stealth stacks cleanly on top of it.

Turnkey Auto-Solve (Autopilot)

auto_solve_* helpers wrap the full detect → solve → inject pipeline into a single call. They wait for captchas that render late, clone the browser context, and support proxy rotation.

from auto_captcha_solver import auto_solve_url

report = auto_solve_url(
    "https://some-login-form.com",
    api_key="your-key",
    stealth=True,          # mask headless fingerprint
    proxy={"scheme": "http", "host": "your-residential-ip", "port": 7777},
)
print(report.summary)   # "https://... — hcaptcha:OK"
print(report.solved)    # True

Rotating proxies (e.g. Novada) — pass a pool; one proxy is picked per session and used for BOTH browser egress and the solve request, so the token IP always matches the browser IP (required for token validity):

from auto_captcha_solver import auto_solve_url, round_robin_rotator

proxies = [
    {"scheme": "http", "host": "p1.novada.example", "port": 7777, "username": "u", "password": "p"},
    {"scheme": "http", "host": "p2.novada.example", "port": 7777, "username": "u", "password": "p"},
]
report = auto_solve_url("https://site.com", api_key="k", proxy_pool=proxies)

Remote / hosted browsers (Browserless, Steel, or any CDP endpoint) — pass cdp_url to drive an existing browser instead of launching one. The function opens a fresh context on the remote browser, solves, and closes that context without killing the remote session:

from auto_captcha_solver import auto_solve_url

report = auto_solve_url(
    "https://site.com",
    api_key="your-key",
    cdp_url="https://<token>.browserless.io?token=***",   # or wss:// Steel endpoint
    # connect_kwargs={"headers": {"Authorization": "Bearer <token>"}},  # if needed
    # proxy={"scheme": "http", "host": "remote-egress-ip", "port": 7777},
    #   ↑ forward the remote browser's egress IP to the solver — the token's IP
    #     must match the client IP or Turnstile/reCAPTCHA v3 will invalidate it.
)

In CDP mode the browser's egress is fixed by the host (you can't re-route it), so match it with proxy for the solve request. Local mode does this automatically: proxy drives both the launched browser and the solver.

Wire it into a page you already own with auto_solve_page(page, solver) — it polls for late-rendering widgets (safer than waiting for networkidle, which Turnstile pages never reach) and solves every challenge on it.

CLI Usage

# Check credits
auto-captcha credits --key $NOPECHA_API_KEY

# Detect only (don't solve)
auto-captcha detect --url https://example.com

# Auto-solve
auto-captcha solve --url https://example.com --key $NOPECHA_API_KEY

# Drive a remote/hosted browser over CDP (Browserless / Steel)
auto-captcha solve --url https://example.com --cdp-url "https://<token>.browserless.io?token=***"
auto-captcha detect --url https://example.com --cdp-url "wss://steel-endpoint" --cdp-header "Authorization: Bearer <token>"

# Proxy (REQUIRED for Turnstile / reCAPTCHA v3 — solver IP must match browser IP)
auto-captcha solve --url https://turnstile-page.com --proxy-url "http://user:pass@host:7777"
auto-captcha solve --url https://turnstile-page.com            # or: --proxy/--proxy-port/--proxy-user/--proxy-pass, or NOVADA_* env
auto-captcha proxy-check --proxy-url "http://user:pass@host:7777"   # verify proxy + show egress IP (no API key)

Results are printed as formatted JSON.

MCP Server

Exposes captcha solving as MCP tools for AI agents (Claude Code, Cursor, etc.):

# Set env var
export NOPECHA_API_KEY="your-key"

# Run as MCP server
python -m auto_captcha_solver.mcp_server

Then register in your client config:

{
  "mcpServers": {
    "auto-captcha": {
      "command": "python",
      "args": ["-m", "auto_captcha_solver.mcp_server"],
      "env": {"NOPECHA_API_KEY": "your-key"}
    }
  }
}

Available tools:

• captcha_detect — scan a URL for captchas
• captcha_solve — detect and solve
• captcha_credits — check API credit balance

Architecture

┌──────────────────┐
│  Your script     │
│  (Playwright)    │
└────────┬─────────┘
         │ calls page.goto() / click()
         ▼
┌──────────────────┐
│   SmartPage      │  ← Detects navigation/click events
│   (wrapper)      │  → Waits → Calls detect() after each action
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  CaptchaSolver   │  ← DOM + frame inspection
│  - detect()      │  → extracts sitekeys
│  - solve()       │  → calls NopeCHA API
│  - inject()      │  → posts token into page callbacks
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  NopeCHA API     │  ← Cloud solver (5–60s)
│  token endpoint  │
└──────────────────┘

Supported Captcha Types

| Type | Status | Notes | |------|--------|-------| | hCaptcha | ✅ Stable | checkbox + invisible | | reCAPTCHA v2 | ✅ Stable | checkbox | | reCAPTCHA v3 | ✅ Stable | score-based, invisible | | Cloudflare Turnstile | ⚠️ Experimental | NopeCHA queue may be slow |

Experimental types work through NopeCHA's queue system (5–10 minute wait, requires proxy in production).

Performance

• Detection: < 100ms (DOM scan)
• Solving time: 5–60 seconds (API-dependent)
• API credits: ~1–5 credits per solve (varies by captcha type & NopeCHA plan)

Production: Proxies & Sticky Sessions

Solving captchas is only one part of stable long-term scraping. Modern sites cross-validate IP identity, persistent cookies, and request behavior as a single risk signal. Even when every challenge is solved successfully, an unstable request pipeline will keep triggering anti-bot restrictions.

For crawlers that run for hours or days, pair this library with residential proxies that support sticky sessions:

• Rotate between sessions — assign each browser context or worker its own proxy endpoint so traffic is spread across IPs.
• Keep the same IP within a session — after a captcha is solved, all follow-up requests (navigation, XHR, cookies) must leave from the same IP that earned the token.
• Match proxy on both sides — configure the same sticky proxy for Playwright and for the NopeCHA solve request so the token and subsequent page loads share one identity.

from playwright.sync_api import sync_playwright
from auto_captcha_solver import CaptchaSolver

# Same sticky res