auto-captcha-solver

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", "[email protected]")
    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", "[email protected]")
    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 Turnsti