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)

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