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 整合