2Captcha MCP

io.github.aruxojuyu665Published by GitHub account aruxojuyu665v0.6.1Updated Oct 27, 2026

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

The publisher's own server: captcha.cc Human Verification

Overview

AI-generated overview

Wraps the full 2Captcha API in 43 tools so an assistant can submit captchas for solving, check balance, and manage pingbacks.

What you can do
  • Submit captchas for solving across 31 types, including image, text, audio, grid, reCAPTCHA, hCaptcha, Turnstile, GeeTest and others
  • Send a captcha and wait for the result in one call, or poll a captcha id manually
  • Check account balance and report a solve as good or bad
  • Register, list and delete pingback callback URLs
  • Run an optional local webhook receiver that stores pingback results in SQLite and exposes tools to list, get and clear them
  • Send raw API requests as an escape hatch for methods not yet exposed
When to use it
Useful when an assistant needs to get past captcha challenges on sites the user is authorized to automate, or to script 2Captcha account tasks such as balance checks and pingback management. Not needed for ordinary browsing or scraping that involves no captcha.
Requirements
Runs locally as a Python stdio process, installed from PyPI and started with uvx or python -m. Requires a 2Captcha API key supplied through an environment variable such as 2Captcha_API_KEY, plus network access to the 2Captcha service. Optional settings cover server choice, timeouts, polling interval and a default pingback URL.
Before you install
Every solve spends money from the 2Captcha account balance, and live tests also consume credits. The API key is a paid credential passed in the environment. Solves send captcha images, site keys, page URLs, cookies, user agents and optional proxy details to 2Captcha, a third party. Pingback registration whitelists callback URLs, and the delete tool can remove all of them at once. Using it to bypass captchas may violate site terms.

Installation

In SourceWeft

  1. Open 2Captcha MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit 8d0b639

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.6.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Captcha integrations