⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

auto-captcha-solver

interfluve-wav@interfluve-wav⭐ 10 stars· last commit 1mo ago· 0 open issues

Universal captcha auto-solver for Playwright browser automation. Detects hCaptcha and reCAPTCHA v2 on any page, solves via NopeCHA API, and injects tokens automatically. Drop-in CaptchaSolver class with auto_solve(page) method.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 10 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

auto-captcha — Universal Captcha Solver for Playwright

Python PyPI version License: MIT MCP Compatible Hermes Skill

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

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • hermes-skill/SKILL.md5.5 KB4f0dee7a1f4dupstream ↗
    ---
    name: auto-captcha-solver
    description: Universal captcha auto-solver for Playwright browser automation. Detects hCaptcha and reCAPTCHA v2 on any page, solves via NopeCHA API, and injects tokens automatically. Drop-in CaptchaSolver class with auto_solve(page) method.
    category: software-development
    ---
    
    # Auto-Captcha
    
    Auto-detect and solve captchas during Playwright browser automation using the NopeCHA API.
    
    ## When to Use
    
    - Browser automation hits a captcha wall
    - Web scraping tasks need captcha bypass
    - Automated testing against captcha-protected sites
    - Any Playwright script that might encounter hCaptcha or reCAPTCHA v2
    
    ## Prerequisites
    
    - `NOPECHA_API_KEY` env var set (get free credits at https://nopecha.com)
    - Python `requests` and `playwright` installed
    - Playwright browser installed (`python -m playwright install chromium`)
    
    ## Quick Start
    
    ```python
    from auto_captcha_solver import CaptchaSolver
    
    solver = CaptchaSolver(api_key="your-key")
    
    # Auto-detect + solve + inject (one-liner)
    results = solver.auto_solve(page)
    ```
    
    ## Full API
    
    ### Detect
    ```python
    captchas = solver.detect(page)
    # Returns: [{"type": "hcaptcha"|"recaptcha2", "sitekey": "...", "url": "...", "frame": ...}]
    ```
    
    ### Solve
    ```python
    result = solver.solve("hcaptcha", sitekey, page_url)
    # Returns: CaptchaResult(success=True, token="...", attempts=5, elapsed_sec=38.0)
    ```
    
    ### Inject
    ```python
    solver.inject(page, "hcaptcha", token)
    # Injects token into page's captcha callback
    ```
    
    ### Auto (detect + solve + inject)
    ```python
    results = solver.auto_solve(page)
    for r in results:
        print(f"{r.captcha_type}: {'OK' if r.success else r.error}")
    ```
    
    ## SmartPage (transparent wrapper)
    
    ```python
    from auto_captcha_solver import smart_page
    
    with smart_page(api_key="your-key") as page:
        page.goto("https://protected-site.com")
        page.fill("#email", "[email protected]")
        page.click("#submit")   # captcha auto-solved after each action
    ```
    
    ## Supported Captcha Types
    
    | Type | API Endpoint | Status |
    |------|-------------|--------|
    | hCaptcha (checkbox) | `/v1/token/hcaptcha` | Working |
    | hCaptcha (enterprise) | `/v1/token/hcaptcha` | Working |
    | reCAPTCHA v2 | `/v1/token/recaptcha2` | Works but queue can be slow |
    | reCAPTCHA v3 | `/v1/token/recaptcha3` | Working (needs `data.action`) |
    | Cloudflare Turnstile | `/v1/token/turnstile` | Working **with a proxy** — proxy is **Required** in NopeCHA's schema for this endpoint (solver exit IP must match browser IP); `check_proxy_egress()` / CLI `proxy-check` verify first. Error 10 bodies carry a diagnostic `type` field, now surfaced in the error string. |
    
    ## Stealth & Context Cloning (v0.1.6)
    
    `apply_stealth(context)` masks the in-page headless leaks (`navigator.webdriver`,
    `window.chrome`, `navigator.plugins`, WebGL vendor string). Call right after
    `browser.new_context(...)`.
    
    ```python
    from auto_captcha_solver import CaptchaSolver, apply_stealth
    from playwright.sync_api import sync_playwright
    
    with sync_playwright() as p:
        browser = p.chromium.launch()
        context = browser.new_context()
        apply_stealth(context)          # mask fingerprint
        page = context.new_page()
        solver = CaptchaSolver(api_key="your-key")
        results = solver.auto_solve(page)   # clones UA + cookies automatically
    ```
    
    `auto_solve(..., clone_context=True)` (default) forwards the browser's real
    User-Agent and cookies to NopeCHA so the token is minted in a context matching
    the presenting browser. Turnstile solves without a proxy emit a warning, because
    Cloudflare requires the solver IP to match the client IP.
    
    ## Turnkey Autopilot
    
    ```python
    from auto_captcha_solver import auto_solve_url
    
    report = auto_solve_url("https://site.com", api_key="key", stealth=True)
    print(report.summary)   # "https://site.com — hcaptcha:OK"
    # proxy_pool=[...] + round_robin_rotator rotate proxies per session;
    # auto_solve_page(page, solver) solves captchas on a page you already own.
    ```
    
    ## NopeCHA API Details
    
    - **Base URL**: `https://api.nopecha.com`
    - **Auth**: `Authorization: Basic <API_KEY>` header (NOT query param, NOT Bearer)
    - **Status check**: `GET /v1/status`
    - **Submit hCaptcha**: `POST /v1/token/hcaptcha` body `{"sitekey": "...", "url": "..."}`
    - **Submit reCAPTCHA**: `POST /v1/token/recaptcha2` body `{"sitekey": "...", "url": "..."}`
    - **Poll result**: `GET /v1/token/<type>?id=<job_id>`
    - **Response**: `{"data": "<token>"}` on success, `{"error": 14}` = still in queue (retryable), other errors = fail
    - **hCaptcha** solves fast (~30-40s). **reCAPTCHA** queue is often slow (60-120s+).
    
    ## Pitfalls
    
    - **reCAPTCHA queues can be slow** — may take 60-120+ seconds during peak times
    - **hCaptcha iframe detection** — look for `hcaptcha.com` in frame URLs; some sites load hCaptcha without an iframe (use DOM fallback: `document.querySelector('[data-sitekey]')`). Always add `time.sleep(3)` after page load for lazy loading.
    - **reCAPTCHA iframe detection** — look for `recaptcha` AND `/anchor` in frame URL; the `?k=<sitekey>` param has the key
    - **reCAPTCHA callback injection** — needs `___grecaptcha_cfg` to exist; if site uses enterprise, injection may fail silently
    - **Credits** — each solve costs 1 credit; check with `solver.get_credits()`
    - **Headless detection** — some sites detect headless browsers; use `headless=False` or stealth plugins if needed
    
    ## Installation
    
    ```bash
    pip install auto-captcha-solver
    python -m playwright install chromium
    ```
    
    ## MCP Server
    
    Works with Claude Code, OpenClaw, and any MCP-compatible agent:
    
    ```bash
    claude mcp add auto-captcha-solver -- python -m auto_captcha_solver.mcp_server
    ```
    
    ## File Location
    
    ```
    ~/.hermes/skills/auto-captcha-solver/
    ```
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/interfluve-wav-auto-captcha-solver-hermes-skill.md

// REPO STATS

10 stars
0 open issues
Last commit: 1mo ago