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

Terminal

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)

Terminal

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:

Setting	Aliases	Default	Range
API key (required)	`2Captcha_API_KEY`, `TWOCAPTCHA_API_KEY`, `2CAPTCHA_API_KEY`, `API_KEY_2CAPTCHA`	—	—
Server	`TWOCAPTCHA_SERVER`	`2captcha.com`	`2captcha.com`, `rucaptcha.com`
Default timeout	`TWOCAPTCHA_DEFAULT_TIMEOUT`	`120` s	1..600
reCAPTCHA timeout	`TWOCAPTCHA_RECAPTCHA_TIMEOUT`	`600` s	1..1200
Polling interval	`TWOCAPTCHA_POLLING_INTERVAL`	`10` s	1..120
Soft id	`TWOCAPTCHA_SOFT_ID`	`4580`	—
Log level	`TWOCAPTCHA_LOG_LEVEL`	`INFO`	DEBUG/INFO/WARNING/ERROR/CRITICAL
Default pingback URL	`TWOCAPTCHA_DEFAULT_CALLBACK`	unset	https URL

Tools

Captcha solvers (31)

Tool	SDK method	Required arguments
`twocaptcha_solve_normal`	`normal`	`file_path` xor `file_base64`
`twocaptcha_solve_text`	`text`	`text`
`twocaptcha_solve_audio`	`audio`	file (xor), `audio_lang`
`twocaptcha_solve_grid`	`grid`	file (xor)
`twocaptcha_solve_canvas`	`canvas`	file (xor)
`twocaptcha_solve_coordinates`	`coordinates`	file (xor)
`twocaptcha_solve_rotate`	`rotate`	`files: list`
`twocaptcha_solve_vkimage`	`vkimage`	`files`, `steps`
`twocaptcha_solve_recaptcha`	`recaptcha`	`sitekey`, `url`, `version`, `enterprise`
`twocaptcha_solve_hcaptcha`	`hcaptcha`	`sitekey`, `url`
`twocaptcha_solve_turnstile`	`turnstile`	`sitekey`, `url` (+ `data`/`pagedata` for CF Challenge)
`twocaptcha_solve_funcaptcha`	`funcaptcha`	`sitekey`, `url`
`twocaptcha_solve_geetest`	`geetest`	`gt`, `challenge`, `url`
`twocaptcha_solve_geetest_v4`	`geetest_v4`	`captcha_id`, `url`
`twocaptcha_solve_capy`	`capy`	`sitekey`, `url`
`twocaptcha_solve_keycaptcha`	`keycaptcha`	`s_s_c_user_id`, `s_s_c_session_id`, two signs, `url`
`twocaptcha_solve_lemin`	`lemin`	`captcha_id`, `div_id`, `url`
`twocaptcha_solve_mtcaptcha`	`mtcaptcha`	`sitekey`, `url`
`twocaptcha_solve_friendly_captcha`	`friendly_captcha`	`sitekey`, `url`
`twocaptcha_solve_cutcaptcha`	`cutcaptcha`	`misery_key`, `apikey`, `url`
`twocaptcha_solve_amazon_waf`	`amazon_waf`	`sitekey`, `iv`, `context`, `url`
`twocaptcha_solve_tencent`	`tencent`	`app_id`, `url`
`twocaptcha_solve_atb_captcha`	`atb_captcha`	`app_id`, `api_server`, `url`
`twocaptcha_solve_datadome` ⚑	`datadome`	`proxy`, `user_agent`, `captcha_url`, `pageurl`
`twocaptcha_solve_captchafox` ⚑	`captchafox`	`proxy`, `user_agent`, `sitekey`, `pageurl`
`twocaptcha_solve_vkcaptcha` ⚑	`vkcaptcha`	`proxy`, `user_agent`, `redirect_uri`
`twocaptcha_solve_prosopo`	`prosopo`	`sitekey`, `pageurl`
`twocaptcha_solve_temu`	`temu`	`body`, `part1..3`
`twocaptcha_solve_altcha`	`altcha`	`pageurl`
`twocaptcha_solve_cybersiara`	`cybersiara`	`master_url_id`, `pageurl`, `cyber_user_agent`
`twocaptcha_solve_yandex_smart`	`yandex_smart`	`sitekey`, `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 -v
ruff 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_balance
pytest -m e2e --run-e2e             # full MCP protocol roundtrip via mcp.client.session

Architecture

server.ts

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.

Composite tool: twocaptcha_solve_and_wait_pingback sends the captcha and waits on the local store
Read tools: twocaptcha_pingback_events_list/get/clear
Deployment: docs/DEPLOY-WEBHOOK.md
Troubleshooting: TROUBLESHOOTING.md

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}