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)

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

Results are JSON lines by default; use --pretty for formatted output.

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

Then register in your client config:

{
  "mcpServers": {
    "auto-captcha": {
      "command": "python",
      "args": ["-m", "auto_captcha.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 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:

Parameter	Default	Description
api_key	required	NopeCHA API key
poll_interval	4.0	Seconds between solve status polls
max_polls	25	Maximum polling attempts
timeout_sec	120.0	Overall timeout before giving up
proxy	None	Optional proxy dict for NopeCHA requests

License

MIT — see LICENSE for details.

Credits

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