2Captcha MCP

io.github.aruxojuyu665由 GitHub 账号 aruxojuyu665 发布v0.6.1更新于 Oct 27, 2026

Full 2Captcha API (43 tools) for Claude Code: 31 captcha solvers + management + webhook.

发布方自己的服务:captcha.cc Human Verification

已验证STDIO仅桌面浏览器自动化安全与监控

概览

AI 生成的概览

把完整的 2Captcha API 封装为 43 个工具,让助手提交验证码求解、查询余额并管理回调地址。

可以做什么
  • 提交 31 种验证码求解,涵盖图片、文字、音频、宫格、reCAPTCHA、hCaptcha、Turnstile、GeeTest 等类型
  • 一次调用提交验证码并等待结果,或按验证码 ID 手动轮询
  • 查询账户余额,并对求解结果标记正确或错误
  • 注册、列出和删除 pingback 回调地址
  • 可选运行本地 webhook 接收器,把回调结果存入 SQLite,并提供列出、读取和清空这些记录的工具
  • 通过原始请求工具调用尚未封装的接口
适用场景
适用于助手需要在用户获授权的网站上处理验证码挑战,或需要脚本化 2Captcha 账户操作(如查余额、管理回调)的场景。普通浏览或不涉及验证码的抓取无需安装。
运行要求
以本地 Python stdio 进程运行,从 PyPI 安装后用 uvx 或 python -m 启动。需要 2Captcha API 密钥,通过 2Captcha_API_KEY 等环境变量提供,并需要访问 2Captcha 服务的网络连接。可选设置包括服务器地址、超时、轮询间隔和默认回调地址。
安装前请注意
每次求解都会从 2Captcha 账户余额扣费,运行实网测试同样消耗额度。API 密钥是付费凭证,通过环境变量传入。求解会把验证码图片、sitekey、页面地址、cookies、user agent 以及可选的代理信息发送给第三方 2Captcha。注册回调会把回调地址加入白名单,删除工具可一次清空全部回调。用于绕过验证码可能违反网站条款。

安装

在 SourceWeft 中

  1. 打开 控制台中的 2Captcha MCP,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

2Captcha MCP

[PyPI version] [Python 3.11+] [CI] [codecov] [mypy: strict] [License: MIT]

MCP server exposing the full 2Captcha API surface — 31 captcha types, 5 management tools, 3 pingback CRUD tools, 3 webhook event-store tools, and 1 composite solve-and-wait tool (43 tools total) — to Claude Code via stdio.

Built on the official 2captcha-python SDK (AsyncTwoCaptcha), so retry/polling/parsing are handled upstream and every captcha type the SDK supports is available the moment the SDK adds it.

Quick start

bash
pip install twocaptcha-mcp# or for development:pip install -e ".[dev]"

Create a .env next to the project root:

bash
2Captcha_API_KEY=your_2captcha_key_here

Verify it works:

bash
python -m twocaptcha_mcp           # starts the stdio server (Ctrl+C to stop)

Register the server with Claude Code:

bash
claude mcp add 2captcha -e 2Captcha_API_KEY=your_2captcha_key_here -- python -m twocaptcha_mcp

After a claude restart, prompt the model with:

"Use twocaptcha_balance to check my account."

Configuration

All settings are environment-driven. Aliases in priority order:

SettingAliasesDefaultRange
API key (required)2Captcha_API_KEY, TWOCAPTCHA_API_KEY, 2CAPTCHA_API_KEY, API_KEY_2CAPTCHA——
ServerTWOCAPTCHA_SERVER2captcha.com2captcha.com, rucaptcha.com
Default timeoutTWOCAPTCHA_DEFAULT_TIMEOUT120 s1..600
reCAPTCHA timeoutTWOCAPTCHA_RECAPTCHA_TIMEOUT600 s1..1200
Polling intervalTWOCAPTCHA_POLLING_INTERVAL10 s1..120
Soft idTWOCAPTCHA_SOFT_ID4580—
Log levelTWOCAPTCHA_LOG_LEVELINFODEBUG/INFO/WARNING/ERROR/CRITICAL
Default pingback URLTWOCAPTCHA_DEFAULT_CALLBACKunsethttps URL

Tools

Captcha solvers (31)

ToolSDK methodRequired arguments
twocaptcha_solve_normalnormalfile_path xor file_base64
twocaptcha_solve_texttexttext
twocaptcha_solve_audioaudiofile (xor), audio_lang
twocaptcha_solve_gridgridfile (xor)
twocaptcha_solve_canvascanvasfile (xor)
twocaptcha_solve_coordinatescoordinatesfile (xor)
twocaptcha_solve_rotaterotatefiles: list
twocaptcha_solve_vkimagevkimagefiles, steps
twocaptcha_solve_recaptcharecaptchasitekey, url, version, enterprise
twocaptcha_solve_hcaptchahcaptchasitekey, url
twocaptcha_solve_turnstileturnstilesitekey, url (+ data/pagedata for CF Challenge)
twocaptcha_solve_funcaptchafuncaptchasitekey, url
twocaptcha_solve_geetestgeetestgt, challenge, url
twocaptcha_solve_geetest_v4geetest_v4captcha_id, url
twocaptcha_solve_capycapysitekey, url
twocaptcha_solve_keycaptchakeycaptchas_s_c_user_id, s_s_c_session_id, two signs, url
twocaptcha_solve_leminlemincaptcha_id, div_id, url
twocaptcha_solve_mtcaptchamtcaptchasitekey, url
twocaptcha_solve_friendly_captchafriendly_captchasitekey, url
twocaptcha_solve_cutcaptchacutcaptchamisery_key, apikey, url
twocaptcha_solve_amazon_wafamazon_wafsitekey, iv, context, url
twocaptcha_solve_tencenttencentapp_id, url
twocaptcha_solve_atb_captchaatb_captchaapp_id, api_server, url
twocaptcha_solve_datadome ⚑datadomeproxy, user_agent, captcha_url, pageurl
twocaptcha_solve_captchafox ⚑captchafoxproxy, user_agent, sitekey, pageurl
twocaptcha_solve_vkcaptcha ⚑vkcaptchaproxy, user_agent, redirect_uri
twocaptcha_solve_prosopoprosopositekey, pageurl
twocaptcha_solve_temutemubody, part1..3
twocaptcha_solve_altchaaltchapageurl
twocaptcha_solve_cybersiaracybersiaramaster_url_id, pageurl, cyber_user_agent
twocaptcha_solve_yandex_smartyandex_smartsitekey, url

⚑ — proxy and user_agent are required by the SDK signature.

All solver tools accept the same set of optional kwargs (mixin SolverKwargs):

  • proxy: {type, uri} (HTTP/HTTPS/SOCKS4/SOCKS5)
  • pingback: HttpUrl — per-call pingback URL (must be pre-registered)
  • soft_id: int
  • cookies: str
  • user_agent: str
  • lang: str
  • header_acao: 0|1

Management (5)

  • twocaptcha_balance — current balance in USD
  • twocaptcha_report_good / twocaptcha_report_bad — report a captcha id within 15 minutes
  • twocaptcha_get_result — poll a captcha id manually (paired with send_raw)
  • twocaptcha_send_raw — escape hatch for SDK methods this server does not yet expose

Pingback CRUD (3)

  • twocaptcha_register_pingback — whitelist a callback URL
  • twocaptcha_list_pingbacks — list whitelisted addresses
  • twocaptcha_delete_pingback — delete one or addr="all"

Development

bash
pytest --cov=twocaptcha_mcp --cov-branch --cov-fail-under=92 -vruff check . && ruff format --check .mypy --strict twocaptcha_mcp

Run live tests against the real 2Captcha API (consumes credits):

bash
pytest -m live --run-live          # balance + solve_normal + concurrent_balancepytest -m e2e --run-e2e             # full MCP protocol roundtrip via mcp.client.session

Architecture

twocaptcha_mcp/├── __main__.py            # stdio entrypoint├── server.py              # build_server + dispatch_tool_call├── config.py              # pydantic-settings (.env)├── logger.py              # stderr-only logger (stdout is reserved for stdio MCP)├── client/│   ├── solver.py          # SolverClient — async wrapper over AsyncTwoCaptcha│   ├── pingback.py        # httpx wrapper for legacy res.php│   ├── rate_limiter.py    # async sliding-window per-method rate limiter│   └── errors.py          # internal CaptchaError hierarchy├── schemas/               # Pydantic request/response models per captcha family├── tools/                 # @captcha_tool handlers per captcha family + composite└── webhook_receiver/      # Starlette app + SQLite store (twocaptcha-mcp-webhook)

Tool handlers depend only on the SolverClient / PingbackClient abstractions — the SDK is never imported from a handler. Adding a new captcha type is a 3-step process: schema → tool handler → snapshot test count bump.

Webhook receiver (optional, since 0.3.0)

For long-running solves (recaptcha v3 up to 600 s), the polling-mode SDK call holds the MCP request slot for the entire duration. Run the optional twocaptcha-mcp-webhook server to flip into pingback mode — 2Captcha POSTs the result to your URL, the receiver writes it to SQLite, and the MCP tools read asynchronously without blocking.

Contributing

See CONTRIBUTING.md for the dev loop, code conventions, and the SemVer policy for the MCP tool surface.

Security

See SECURITY.md. Vulnerabilities are reported privately via GitHub Security Advisory.

License

MIT — see LICENSE.


Registry verification — mcp-name: io.github.aruxojuyu665/twocaptcha-mcp

来源:README.md,提交 8d0b639

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.6.1最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

其他 Captcha 集成