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
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

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 residential proxy for browser traffic and token API
proxy = {
    "scheme": "http",
    "host": "gate.provider.com",
    "port": 7777,
    "username": "user-session-abc123",  # session id pins the IP
    "password": "secret",
}

playwright_proxy = {
    "server": f"http://{proxy['host']}:{proxy['port']}",
    "username": proxy["username"],
    "password": proxy["password"],
}

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

with sync_playwright() as pw:
    browser = pw.chromium.launch(headless=False, proxy=playwright_proxy)
    page = browser.new_page()
    page.goto("https://cloudflare-heavy-site.com")
    solver.auto_solve(page)  # token solved from the same IP as the browser

Practical tips:

• One sticky session per browser context — do not rotate mid-crawl after a solve.
• Reuse cookies/storage for the lifetime of that session; discard the context when you rotate IPs.
• For Cloudflare-heavy targets (e.g. SERP crawling), residential sticky proxies noticeably reduce repeat challenges compared to captcha solving alone.

Residential providers with session pinning work well with this pattern. For example, Novada pins an IP by appending session-{id} to the proxy username (e.g. USERNAME-zone-res-session-job42:PASSWORD on super.novada.pro:7777). Any provider that supports sticky sessions and HTTP proxy auth is fine — the key is keeping browser and solver traffic on the same IP.

Configuration

CaptchaSolver constructor arguments:

License

MIT — see LICENSE for details.

Credits

• Built by Suhaas Chitturi
• API powered by NopeCHA
• Diagram assets: Mermaid / Excalidraw