English Français العربية

2Captcha MCP

Official registry Developer tools

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

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package twocaptcha-mcp
Claude Code 
claude mcp add 2captcha-mcp -e '2Captcha_API_KEY=<your 2captcha_api_key>' -- uvx twocaptcha-mcp==0.6.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "2captcha-mcp": {
            "command": "uvx",
            "args": [
                "twocaptcha-mcp==0.6.1"
            ],
            "env": {
                "2Captcha_API_KEY": "<your 2captcha_api_key>"
            }
        }
    }
}

Environment variables

  • 2Captcha_API_KEY required secret 2Captcha account API key (https://2captcha.com/setting)

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. 2Captcha MCP
  2. Quick start
  3. Configuration
  4. Tools
  5. Development
  6. Architecture
  7. Webhook receiver (optional, since 0.3.0)
  8. Contributing
  9. Security
  10. License

2Captcha MCP

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

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

Create a .env next to the project root:

2Captcha_API_KEY=your_2captcha_key_here

Verify it works:

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

Register the server with Claude Code:

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

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

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

pytest -m live --run-live          # balance + solve_normal + concurrent_balance
pytest -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

Frequently asked questions

What is 2Captcha MCP?

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

How do I install 2Captcha MCP?

It runs on your machine. In Claude Code: claude mcp add 2captcha-mcp -e '2Captcha_API_KEY=<your 2captcha_api_key>' -- uvx twocaptcha-mcp==0.6.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does 2Captcha MCP need an API key?

Yes. It expects 2Captcha_API_KEY, which you set in its configuration.

Is 2Captcha MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains 2Captcha MCP?

It is published by aruxojuyu665. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.