⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
auto-captcha-solver
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.
// RATINGS
// README
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 —
CaptchaSolverclass 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-cliworkflows
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 browserwait_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 readsdata-action/data-cdataoff 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 withoutproxy=.... - The
Runtime.enableCDP leak (below the JS layer) is closed only by driving the browser with Patchright — a drop-in Playwright fork.apply_stealthstacks 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