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:

Tools

Captcha solvers (31)

⚑ — 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.

• 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