Captcha

CAPTCHA Solver Skill

Solve CAPTCHAs programmatically in web automation workflows.

How Token-Based CAPTCHA Solving Works

Modern CAPTCHAs (reCAPTCHA, hCaptcha, Turnstile) don't require reading distorted text — they issue a signed token when solved. A third-party service solves the challenge on your behalf and returns that token. You inject it into the page, and the page thinks the user solved it.

Page with CAPTCHA
    │
    ├─ 1. Extract sitekey + page URL
    ├─ 2. Submit to solving service (waits 15–45s)
    ├─ 3. Receive token string
    ├─ 4. Inject token into hidden field on page
    ├─ 5. Trigger the CAPTCHA callback
    └─ 6. Submit form / continue automation

Tokens expire in ~2 minutes — solve immediately before submitting.

Supported CAPTCHA Types

Read references/captcha-types.md for per-type detection JS snippets and injection patterns.

Solving Services

You need an API key from a solving service. All three below use the same API format, so the solver script works with any of them:

Set credentials via environment variables (preferred):

export CAPTCHA_API_KEY=your_key_here
export CAPTCHA_SERVICE=2captcha

Read references/services.md for signup links, free trial details, and API compatibility.

Setup

Copy the solver script to your project before using it:

# From your project directory — adjust path to match your skill install location
cp ~/.claude/plugins/captcha/scripts/solve_captcha.py ./solve_captcha.py

The script uses only Python stdlib — no pip install needed.

Quick Start: reCAPTCHA v2

Using the bundled script (recommended)

python solve_captcha.py \
  --type recaptcha-v2 \
  --sitekey 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- \
  --pageurl https://www.google.com/recaptcha/api2/demo \
  --api-key $CAPTCHA_API_KEY
# → {"success": true, "token": "03AGdBq25...", "type": "recaptcha-v2"}

Full Playwright workflow (Python)

Key insight: start solving before you open the browser. The service takes 15–40s to return a token. If you kick off the solve call first, that wait happens in the background while you launch the browser and navigate — free parallelism.

import json, os, subprocess, sys
from playwright.sync_api import sync_playwright

SOLVER = "solve_captcha.py"   # must be in same directory or on PATH

def solve(captcha_type, sitekey, pageurl, service=None):
    cmd = [sys.executable, SOLVER,
           "--type", captcha_type,
           "--sitekey", sitekey,
           "--pageurl", pageurl]
    if service:
        cmd += ["--service", service]
    result = subprocess.run(cmd, capture_output=True, text=True, env=os.environ)
    data = json.loads(result.stdout)
    if not data["success"]:
        raise RuntimeError(data["error"])
    return data["token"]

PAGE_URL = "https://www.google.com/recaptcha/api2/demo"
SITEKEY  = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"

# Step 1: start solving (this takes 15–40s) — do it BEFORE opening the browser
token = solve("recaptcha-v2", SITEKEY, PAGE_URL)

# Step 2: now launch and navigate — solve is already done or finishing
with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = browser.new_page()
    page.goto(PAGE_URL)

    # Step 3: inject token — use json.dumps() for safe JS interpolation
    import json as _json
    token_js = _json.dumps(token)
    page.evaluate(f"""
        const token = {token_js};
        const el = document.querySelector('[name="g-recaptcha-response"]');
        if (el) {{ el.value = token; }}
        if (window.___grecaptcha_cfg) {{
            Object.values(window.___grecaptcha_cfg.clients || {{}}).forEach(c => {{
                Object.keys(c).forEach(k => {{
                    if (c[k]?.callback) c[k].callback(token);
                }});
            }});
        }}
    """)

    page.click('#recaptcha-demo-submit')
    browser.close()

Important: Always use json.dumps(token) when embedding a token in JS — never bare f-string interpolation like '{token}'. Token strings are base64url-safe today but the pattern is fragile.

Step-by-Step Workflow

Step 1 — Detect CAPTCHA type and extract sitekey

Run this JS in the browser (via page.evaluate or browser_evaluate):

(() => {
  const q = s => document.querySelector(s);
  if (q('.g-recaptcha, [data-sitekey]:not(.h-captcha):not(.cf-turnstile)'))
    return { type: 'recaptcha-v2', sitekey: q('[data-sitekey]')?.dataset?.sitekey };
  if (q('.h-captcha, [data-hcaptcha-sitekey]'))
    return { type: 'hcaptcha', sitekey: q('[data-sitekey]')?.dataset?.sitekey };
  if (q('.cf-turnstile'))
    return { type: 'turnstile', sitekey: q('.cf-turnstile')?.dataset?.sitekey };
  if (q('img[src*="captcha" i], img[alt*="captcha" i]'))
    return { type: 'image' };
  return { type: null };
})();

For reCAPTCHA v3 (no visible widget), look in the page source for:

grecaptcha.execute('SITEKEY', {action: 'ACTION_NAME'})

Step 2 — Run the solver script

Always use solve_captcha.py for the API call — don't write your own polling loop. The script handles initial wait, retries, error codes, and service switching.

# reCAPTCHA v2
python solve_captcha.py --type recaptcha-v2 --sitekey SITEKEY --pageurl URL

# reCAPTCHA v3
python solve_captcha.py --type recaptcha-v3 --sitekey SITEKEY --pageurl URL --action verify

# hCaptcha
python solve_captcha.py --type hcaptcha --sitekey SITEKEY --pageurl URL

# Cloudflare Turnstile
python solve_captcha.py --type turnstile --sitekey SITEKEY --pageurl URL

# Image CAPTCHA (send screenshot of the captcha image)
python solve_captcha.py --type image --image captcha_screenshot.png

Step 3 — Inject the token

Each CAPTCHA type has a different injection pattern. Read references/captcha-types.md for the exact JS for each type.

reCAPTCHA v2 (most common):

// 1. Set the hidden response field
document.querySelector('[name="g-recaptcha-response"]').value = TOKEN;

// 2. Trigger the registered callback
if (window.___grecaptcha_cfg) {
  Object.values(window.___grecaptcha_cfg.clients || {}).forEach(client => {
    Object.keys(client).forEach(key => {
      if (client[key]?.callback) client[key].callback(TOKEN);
    });
  });
}

Image Grid Challenge (Vision AI)

Sometimes after clicking the reCAPTCHA v2 checkbox a grid appears: "Select all images with traffic lights". This is a separate visual challenge — token solving won't help here. The bundled solve_image_grid.py handles it by screenshotting the grid and asking a vision AI (Claude or GPT-4V) which cells to click.

Requirements: pip install anthropic   (or openai as fallback)
Environment:  ANTHROPIC_API_KEY  or  OPENAI_API_KEY

How it works

Checkbox clicked
    │
    ├─ Grid appeared? → screenshot grid cells → ask vision AI → click matching cells
    │                                                          → click Verify
    │                                                          → new round? → repeat
    └─ No grid (trusted IP) → returns True immediately

Integration with your script

from playwright.sync_api import sync_playwright
from solve_image_grid import solve_image_grid  # copy from scripts/

with sync_playwright() as p:
    page = p.chromium.launch(headless=False).new_page()
    page.goto("https://www.google.com/recaptcha/api2/demo")

    # Step 1: click the checkbox (inside its iframe)
    page.frame_locator('iframe[title="reCAPTCHA"]') \
        .locator('.recaptcha-checkbox-border').click()

    # Step 2: handle grid if it appears (returns immediately if no grid)
    solved = solve_image_grid(page)

    if solved:
        page.click('#recaptcha-demo-submit')

Combined flow (grid + token fallback)

Some pages require the grid challenge AND a token. Handle both:

import json, os, subprocess, sys
from solve_image_grid import solve_image_grid

SOLVER = "solve_captcha.py"
SITEKEY = "your-sitekey"

# 1. Click checkbox — may or may not trigger a grid
page.frame_locator('iframe[title="reCAPTCHA"]') \
    .locator('.recaptcha-checkbox-border').click()

# 2. Solve grid if it appeared
grid_ok = solve_image_grid(page)

# 3. If the form still needs a token (check for g-recaptcha-response being empty)
token_empty = page.evaluate(
    "document.querySelector('[name=\"g-recaptcha-response\"]')?.value === ''"
)
if grid_ok and token_empty:
    result = subprocess.run(
        [sys.executable, SOLVER, "--type", "recaptcha-v2",
         "--sitekey", SITEKEY, "--pageurl", page.url],
        capture_output=True, text=True, env=os.environ
    )
    token = json.loads(result.stdout)["token"]
    token_js = json.dumps(token)
    page.evaluate(f"""
        const t = {token_js};
        document.querySelector('[name="g-recaptcha-response"]').value = t;
        if (window.___grecaptcha_cfg)
            Object.values(window.___grecaptcha_cfg.clients||{{}}).forEach(c=>
                Object.keys(c).forEach(k=>{{ if(c[k]?.callback) c[k].callback(t) }})
            );
    """)

Notes

• Element clicks vs pixel coordinates — the script clicks grid cells via frame_locator().locator('td').nth(i), not raw pixel coordinates. This is more reliable across different viewport sizes and DPI settings.
• Multi-round challenges — Google often shows 2–4 rounds. The script loops automatically up to max_rounds=6.
• "None of the above" rounds — if the AI returns [] (no matches), the script clicks Verify anyway. Google sometimes accepts this.
• Accuracy — Claude Opus performs well on clear images (~80–90% first-round accuracy). Blurry or ambiguous grids may need multiple rounds.

Using Playwright MCP Tools

If Playwright MCP tools are available (mcp__plugin_playwright_playwright__*):

1. browser_navigate → go to the page
2. browser_evaluate → run detection JS to find CAPTCHA type and sitekey
3. Bash → python scripts/solve_captcha.py ... (takes 15-40s)
4. browser_evaluate → inject token + trigger callback
5. browser_click → submit button
6. browser_snapshot → verify success

Troubleshooting

Reference Files

• scripts/solve_captcha.py — CLI solver for token-based CAPTCHAs (stdlib only, no pip install)
• scripts/solve_image_grid.py — Vision AI solver for reCAPTCHA v2 image grid challenges
• references/captcha-types.md — Detection + injection JS for each CAPTCHA type
• references/services.md — Service comparison, signup, pricing, API keys
• references/stealth.md — Avoiding bot detection after bypassing CAPTCHA