io.github.CapMonsterCloud/capmonster-mcp-captcha-solver

Submit a captcha task; returns taskId. Poll with get_task_result. task must include 'type' and all required fields. Always look up required params at https://docs.capmonster.cloud/docs/captchas/ — do not rely on training data. For a task holding one or more large base64 blobs (ComplexImageTask with several images, htmlPageBase64 for Cloudflare cf_clearance/wait_room, or any other opaque field/combined payload too big to type safely) pass `task_file` instead of `task`: the path to a JSON file, on this machine's filesystem, containing the exact task object. Write that file with a script or a browser-side save (never by hand-typing a long base64 literal into this tool call's own arguments — a single dropped/unclosed quote in a multi-KB string silently merges what should be separate array elements into one, which is why this exists: a 9-image ComplexImageTask sent inline this way became "Image count: 1, but the task supports: 9" even though the array had 9 entries when written). Provide exactly one of `task` or `task_file`.

Fetch a current, real-world (Windows) User-Agent string from CapMonster's UA service. Use ONE User-Agent as a single fingerprint thread across the whole solve — they must all match or the solved token is likely to be rejected: 1. set it as the patchright browser context's UA (browser-launch flag / device emulation), so the page is loaded with it; 2. pass the SAME string as the `userAgent` field of any CapMonster task that accepts one (reCAPTCHA, Turnstile/Cloudflare, FunCaptcha, AWS WAF, DataDome, Imperva, Yidun, TenDI, …); 3. when the solution comes back with its own `userAgent` (or `headers["User-Agent"]`), the token is bound to THAT value — reuse it for the injection and any follow-up requests instead of your original. CapMonster requires a current Windows-OS UA; a stale/invalid one fails with ERROR_WRONG_USERAGENT, so re-fetch here rather than reusing an old one.

Get CapMonster account balance.

Fetch a CapMonster documentation page by its URL and return its text. Use this to read a captcha type's docs (exact task parameters, how to extract them from a live page, and worked createTask/getTaskResult examples). Pick the URL from the llms.txt index (https://docs.capmonster.cloud/llms.txt) — it lists every doc page. Also accepts llms-full.txt and the OpenAPI spec URL. Only URLs on docs.capmonster.cloud or api.capmonster.cloud are allowed. Jumping to a section (preferred on big pages — avoids paging by hand): - Pass `section="<heading>"` to return just that `##`/`###` section (from its heading down to the next same-or-higher-level heading). Matching is case-insensitive and substring-based, so `section="Examples of solving"` or even `section="examples"` works. Great for going straight to "Create task", "Get task result", or "Examples of solving …". - When a page is returned in chunks, the first chunk is prefixed with a section outline (each heading and the exact `section="…"` to jump to it), so you can pick the section you need in one follow-up call. Paging (when you want the raw text, no section): Pages that don't fit in `limit` characters are returned one chunk at a time, starting at `offset`. The chunk is prefixed with a header showing the range, the total length, and (if there's more) the `offset` to pass on the next call — keep calling with that offset until the header says end of document.

List captcha task types supported by CapMonster, sourced from the OpenAPI spec.

Return the parameters for a CapMonster task type, from the live OpenAPI spec. Use after get_supported_tasks() to look up what fields a task needs. Pass either a top-level type name (e.g. 'RecaptchaV2Task', 'TurnstileTask') or a CustomTask class name (e.g. 'DataDome', 'altcha', 'HUNT'). Returns: - all_parameters: every field with its type/description (nested objects like `metadata` are expanded). - required: the fields the spec marks required. - description: the type's own spec note. READ IT — for several types it is where the spec records that the type has mutually-exclusive VARIANTS and which fields each needs (e.g. Turnstile's `cloudflareTaskType`, AWS WAF's challenge/captcha/cookie option-sets). The flat `required` list CANNOT express those variants, so it under-reports what a given variant needs. - solution: the name of the solution schema this type returns. ⚠️ The flat field list is a starting point, not the whole contract. When `description` mentions variants/options/modes — or whenever you are unsure — confirm the exact per-variant field set and the solution shape against the worked examples via get_docs before building the task.

Fetch a task result ONCE (a single poll). Prefer `get_task_result_wait`, which polls for you. Use this only if you want to drive the poll loop yourself. Returns a dict: - while solving: {"status": "processing", ...} — retry after 2-3 s. Poll no faster than once per 2 s (max 120 polls per task), and fetch the result promptly: the task is stored for only ~5 min before it expires with ERROR_NO_SUCH_CAPCHA_ID. - when ready: {"status": "ready", "solution": {...}, "cost": ..., ...} The `solution` object is CapMonster's raw solution, returned verbatim — its shape differs per captcha type. Extract fields by the shape documented for that type (get_docs), e.g. `gRecaptchaResponse`/`token` for reCAPTCHA/Turnstile, nested `domains[host].cookies.*` for DataDome/Imperva, `data.randstr` + `data.ticket` for TenDI, etc. IMPORTANT: several types return a `userAgent` (or `headers["User-Agent"]`) inside the solution — the solved token is bound to it, so reuse that exact UA in the browser / subsequent requests when injecting (Cloudflare Challenge, FunCaptcha, AWS WAF, Binance, TenDI, Basilisk).

Poll a task to completion and return its solution (the usual way to collect a result after create_task). Blocks, polling /getTaskResult every `poll_interval_seconds` until the task is ready or `timeout_seconds` elapses. This respects CapMonster's limits for you — the interval is clamped to a minimum of 2 s (the API rejects faster polling with ERROR_TOO_MUCH_REQUESTS) and the number of polls is capped at 120 per task. Returns the same ready dict as get_task_result: {"status": "ready", "solution": {...}, "cost": ..., ...} The `solution` is CapMonster's raw solution, verbatim — its shape differs per captcha type (see get_task_result / get_docs). IMPORTANT: several types return a `userAgent` (or `headers["User-Agent"]`) inside the solution — the token is bound to it, so reuse that exact UA when injecting (Cloudflare Challenge, FunCaptcha, AWS WAF, Binance, TenDI, Basilisk). Raises an error on solve error (e.g. ERROR_RECAPTCHA_TIMEOUT — often a slow proxy) or if the task is still processing when `timeout_seconds` is reached (increase the timeout, or check the proxy/params and re-create the task).