MCP Tools Reference | CaptchaSonic Docs

托管服务器（https://mcp.captchasonic.com）和本地包（@captchasonic/mcp-server）提供相同的五个工具。求解按常规 API 价格从您的 API 密钥扣费；失败和超时的求解会退款。

Solve token CAPTCHA

solve_token_captcha

求解网页上的令牌型验证码并等待令牌返回（通常 5–60 秒）。支持进度通知的客户端会在求解期间显示 “Solving… Ns”。

参数	类型	说明
`type`	string	下表中的令牌类型之一。
`website_url`	string	验证码所在页面的完整 URL。
`website_key`	string	页面中的 sitekey：`data-sitekey`、`render=` 参数或 GeeTest 的 `captchaId`（v4）/ `gt`（v3）。大多数类型必填。
`proxy`	string	可选。通过您的代理求解，例如 `http://user:[email protected]:8080`。省略则不使用代理。
`metadata`	object	可选。额外的验证码数据，例如企业版页面的 `{ "rqdata": "…" }` 或 GeeTest v3 的 `{ "gt": "…", "challenge": "…" }`。
`task_timeout`	integer	可选。求解器可用的秒数，60–120（默认 120）。
`wait_for_result`	boolean	可选，默认 `true`。设为 `false` 会立即返回 `task_id`，之后用 `get_task_result` 获取令牌。

`type`	验证码	必填	价格
`recaptcha_v2`	reCAPTCHA v2（复选框、隐形）	`website_url`、`website_key`	$0.0005
`recaptcha_v3`	reCAPTCHA v3	`website_url`、`website_key`	$0.001
`turnstile`	Cloudflare Turnstile	`website_url`（建议提供 sitekey）	$0.0005
`cloudflare_challenge`	Cloudflare 验证页（`cf_clearance`）	`website_url`	$0.0005
`popularcaptcha`	PopularCaptcha / hCaptcha 类	`website_url`、`website_key`	$0.0025
`geetest`	GeeTest v3 / v4	`website_url`、`website_key`	$0.0005
`mtcaptcha`	MTCaptcha	`website_url`、`website_key`	$0.0005

结果

{
  "task_id": "9f2c4e1a7b3d5c60",
  "status": "ready",
  "token": "0.Zm9vYmFy…",
  "user_agent": "Mozilla/5.0 …",
  "cookies": { "cf_clearance": "…" }
}

将 token 填入验证码组件使用的表单字段（g-recaptcha-response、cf-turnstile-response、h-captcha-response 等）。对于 cloudflare_challenge，设置返回的 cookies，并使用相同的 user_agent（以及相同的代理，如有）发送后续请求。如果结果为 "status": "processing"，请用 task_id 调用 get_task_result。

Solve image CAPTCHA

solve_image_captcha

求解图片或音频验证码，并立即返回答案。

参数	类型	说明
`type`	string	下表中的图片类型之一。
`images`	string[]	按顺序排列的题目图片（1–50 张）：base64、`data:` URL 或公开的 `http(s)` URL。每张最大 5 MB，所有图片和示例合计约 7.8 MB。
`question`	string	与屏幕上完全一致的题目文字，例如 `Select all images with a bus`。
`question_type`	string	仅限 `popularcaptcha_image`：`objectClassify`、`objectClick`、`objectDrag`、`objectTag`、`grid`、`bbox`、`bboxdd`。
`examples`	string[]	最多 3 张参考图片，例如滑块拼图块。
`website_url`	string	可选的页面 URL，可提升部分求解器的效果。
`module`、`numeric`、`case_sensitive`、`max_length`		OCR 选项。

`type`	验证码	必填	`question`	答案
`popularcaptcha_image`	PopularCaptcha / hCaptcha 类图片	`images`、`question`	题目文字；已知时设置 `question_type`	分类：每张图片一个布尔值。点选：每张图片的 `{x,y}` 坐标点。拖动：每张图片的 `{start,end}`。
`recaptcha_v2_image`	reCAPTCHA v2 网格	`images`、`question`	目标，例如 `traffic lights`，或 `/m/` 代码	单张 3x3/4x4 网格图：匹配格子的索引（从 0 开始）。单独的格子图：每格一个布尔值。
`geetest_image`	GeeTest 九宫格、点选、滑块、match	`images`、`question`	`geetest_nine:<题目>`、`geetest_click:<题目>`、`geetest_slide`（拼图块放在 `examples`）、`match`	九宫格：每格一个布尔值。点选：点击坐标。滑块：`[x, y]` 偏移。match：两个格子索引。
`aws_waf_image`	AWS WAF 网格	`images`、`question`	例如 `Choose all the chairs`	匹配格子的索引（从 0 开始）。
`tiktok_image`	TikTok 旋转、滑块、点选	`images`、`question`	`tiktok_whirl`、`tiktok_slide`（均需 `examples`）、`tiktok_click`	求解器答案（旋转 / 偏移 / 点击），包在单元素列表中。
`binance_image`	Binance 网格、滑块	`images`、`question`	`binance_grid:<目标>`、`binance_slide`（拼图块放在 `examples`）	网格：匹配的格子。滑块：`[x, y]` 偏移。
`tencent_image`	腾讯网格、点选、滑块	`images`	`tencent_grid:<目标>`、`tencent_click`（需要 `examples`）、`tencent_slide`（默认）	网格/点选：`{sol: [[x, y]…], size}`。滑块：`[x, y]` 及 `size`。
`prosopo_image`	Prosopo / Procaptcha	`images`、`question`	题目文字	匹配的格子。
`slide_image`	通用滑块	`images`	—	`[x, y]` 偏移。先背景图，后拼图块（或放在 `examples`）。
`ocr`	文字图片	`images`	—	每张图片一个字符串。
`mtcaptcha_image`	MTCaptcha 文字	`images`	—	每张图片一个字符串。
`audio`	音频验证码	`images`（音频文件）	—	转写的文字。

每个结果都包含 answer_format，用自然语言说明如何使用 answers。

Get task result

get_task_result

参数	类型	说明
`task_id`	string	`solve_token_captcha` 返回的 `task_id`。

返回结构与 solve_token_captcha 相同。结果在就绪后几分钟内过期。

ERROR_ZERO_BALANCE: CaptchaSonic API error 10
The account has no balance. Top up at https://my.captchasonic.com.

错误码	含义
`ERROR_KEY_DOES_NOT_EXIST`	API 密钥缺失、错误或已撤销。
`ERROR_ZERO_BALANCE`	请充值余额。
`ERROR_CAPTCHA_UNSOLVABLE`	无法求解；请加载新的验证码后重试。已退款。
`ERROR_CAPTCHA_TIMEOUT`	未在 `task_timeout` 内求解。已退款。
`ERROR_MISSING_REQUIRED_FIELDS`	缺少该 `type` 的必填参数。
`ERROR_DAILY_LIMIT_EXCEEDED`、`ERROR_MINUTE_LIMIT_EXCEEDED`	已达到套餐限额。
`ERROR_SERVICE_UNAVAILABLE`	服务繁忙；会自动重试，仍失败时返回此错误。

当缺少 Authorization 请求头时，托管服务器还会返回 HTTP 401；当某个密钥每分钟发出超过 120 个 MCP 请求（每次工具调用和建立连接都计入）时返回 429。

MCP 工具参考

Solve token CAPTCHA

Solve image CAPTCHA

Get task result

Get balance

List CAPTCHA types

Errors