{
  "markdown": "# 2Captcha MCP\n\n[![PyPI version](https://img.shields.io/pypi/v/twocaptcha-mcp.svg)](https://pypi.org/project/twocaptcha-mcp/)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![CI](https://github.com/aruxojuyu665/2Captcha-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/aruxojuyu665/2Captcha-MCP/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/aruxojuyu665/2Captcha-MCP/branch/main/graph/badge.svg)](https://codecov.io/gh/aruxojuyu665/2Captcha-MCP)\n[![mypy: strict](https://img.shields.io/badge/mypy-strict-success.svg)](https://mypy.readthedocs.io/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](#license)\n\nMCP 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.\n\nBuilt 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.\n\n## Quick start\n\n```bash\npip install twocaptcha-mcp\n# or for development:\npip install -e \".[dev]\"\n```\n\nCreate a `.env` next to the project root:\n\n```bash\n2Captcha_API_KEY=your_2captcha_key_here\n```\n\nVerify it works:\n\n```bash\npython -m twocaptcha_mcp           # starts the stdio server (Ctrl+C to stop)\n```\n\nRegister the server with Claude Code:\n\n```bash\nclaude mcp add 2captcha -e 2Captcha_API_KEY=your_2captcha_key_here -- python -m twocaptcha_mcp\n```\n\nAfter a `claude` restart, prompt the model with:\n\n> \"Use twocaptcha_balance to check my account.\"\n\n## Configuration\n\nAll settings are environment-driven. Aliases in priority order:\n\n| Setting | Aliases | Default | Range |\n|---|---|---|---|\n| API key (required) | `2Captcha_API_KEY`, `TWOCAPTCHA_API_KEY`, `2CAPTCHA_API_KEY`, `API_KEY_2CAPTCHA` | — | — |\n| Server | `TWOCAPTCHA_SERVER` | `2captcha.com` | `2captcha.com`, `rucaptcha.com` |\n| Default timeout | `TWOCAPTCHA_DEFAULT_TIMEOUT` | `120` s | 1..600 |\n| reCAPTCHA timeout | `TWOCAPTCHA_RECAPTCHA_TIMEOUT` | `600` s | 1..1200 |\n| Polling interval | `TWOCAPTCHA_POLLING_INTERVAL` | `10` s | 1..120 |\n| Soft id | `TWOCAPTCHA_SOFT_ID` | `4580` | — |\n| Log level | `TWOCAPTCHA_LOG_LEVEL` | `INFO` | DEBUG/INFO/WARNING/ERROR/CRITICAL |\n| Default pingback URL | `TWOCAPTCHA_DEFAULT_CALLBACK` | _unset_ | https URL |\n\n## Tools\n\n### Captcha solvers (31)\n\n| Tool | SDK method | Required arguments |\n|---|---|---|\n| `twocaptcha_solve_normal` | `normal` | `file_path` xor `file_base64` |\n| `twocaptcha_solve_text` | `text` | `text` |\n| `twocaptcha_solve_audio` | `audio` | file (xor), `audio_lang` |\n| `twocaptcha_solve_grid` | `grid` | file (xor) |\n| `twocaptcha_solve_canvas` | `canvas` | file (xor) |\n| `twocaptcha_solve_coordinates` | `coordinates` | file (xor) |\n| `twocaptcha_solve_rotate` | `rotate` | `files: list` |\n| `twocaptcha_solve_vkimage` | `vkimage` | `files`, `steps` |\n| `twocaptcha_solve_recaptcha` | `recaptcha` | `sitekey`, `url`, `version`, `enterprise` |\n| `twocaptcha_solve_hcaptcha` | `hcaptcha` | `sitekey`, `url` |\n| `twocaptcha_solve_turnstile` | `turnstile` | `sitekey`, `url` (+ `data`/`pagedata` for CF Challenge) |\n| `twocaptcha_solve_funcaptcha` | `funcaptcha` | `sitekey`, `url` |\n| `twocaptcha_solve_geetest` | `geetest` | `gt`, `challenge`, `url` |\n| `twocaptcha_solve_geetest_v4` | `geetest_v4` | `captcha_id`, `url` |\n| `twocaptcha_solve_capy` | `capy` | `sitekey`, `url` |\n| `twocaptcha_solve_keycaptcha` | `keycaptcha` | `s_s_c_user_id`, `s_s_c_session_id`, two signs, `url` |\n| `twocaptcha_solve_lemin` | `lemin` | `captcha_id`, `div_id`, `url` |\n| `twocaptcha_solve_mtcaptcha` | `mtcaptcha` | `sitekey`, `url` |\n| `twocaptcha_solve_friendly_captcha` | `friendly_captcha` | `sitekey`, `url` |\n| `twocaptcha_solve_cutcaptcha` | `cutcaptcha` | `misery_key`, `apikey`, `url` |\n| `twocaptcha_solve_amazon_waf` | `amazon_waf` | `sitekey`, `iv`, `context`, `url` |\n| `twocaptcha_solve_tencent` | `tencent` | `app_id`, `url` |\n| `twocaptcha_solve_atb_captcha` | `atb_captcha` | `app_id`, `api_server`, `url` |\n| `twocaptcha_solve_datadome` ⚑ | `datadome` | `proxy`, `user_agent`, `captcha_url`, `pageurl` |\n| `twocaptcha_solve_captchafox` ⚑ | `captchafox` | `proxy`, `user_agent`, `sitekey`, `pageurl` |\n| `twocaptcha_solve_vkcaptcha` ⚑ | `vkcaptcha` | `proxy`, `user_agent`, `redirect_uri` |\n| `twocaptcha_solve_prosopo` | `prosopo` | `sitekey`, `pageurl` |\n| `twocaptcha_solve_temu` | `temu` | `body`, `part1..3` |\n| `twocaptcha_solve_altcha` | `altcha` | `pageurl` |\n| `twocaptcha_solve_cybersiara` | `cybersiara` | `master_url_id`, `pageurl`, `cyber_user_agent` |\n| `twocaptcha_solve_yandex_smart` | `yandex_smart` | `sitekey`, `url` |\n\n⚑ — `proxy` and `user_agent` are **required** by the SDK signature.\n\nAll solver tools accept the same set of optional kwargs (mixin `SolverKwargs`):\n\n- `proxy: {type, uri}` (HTTP/HTTPS/SOCKS4/SOCKS5)\n- `pingback: HttpUrl` — per-call pingback URL (must be pre-registered)\n- `soft_id: int`\n- `cookies: str`\n- `user_agent: str`\n- `lang: str`\n- `header_acao: 0|1`\n\n### Management (5)\n\n- `twocaptcha_balance` — current balance in USD\n- `twocaptcha_report_good` / `twocaptcha_report_bad` — report a captcha id within 15 minutes\n- `twocaptcha_get_result` — poll a captcha id manually (paired with `send_raw`)\n- `twocaptcha_send_raw` — escape hatch for SDK methods this server does not yet expose\n\n### Pingback CRUD (3)\n\n- `twocaptcha_register_pingback` — whitelist a callback URL\n- `twocaptcha_list_pingbacks` — list whitelisted addresses\n- `twocaptcha_delete_pingback` — delete one or `addr=\"all\"`\n\n## Development\n\n```bash\npytest --cov=twocaptcha_mcp --cov-branch --cov-fail-under=92 -v\nruff check . && ruff format --check .\nmypy --strict twocaptcha_mcp\n```\n\nRun live tests against the real 2Captcha API (consumes credits):\n\n```bash\npytest -m live --run-live          # balance + solve_normal + concurrent_balance\npytest -m e2e --run-e2e             # full MCP protocol roundtrip via mcp.client.session\n```\n\n## Architecture\n\n```\ntwocaptcha_mcp/\n├── __main__.py            # stdio entrypoint\n├── server.py              # build_server + dispatch_tool_call\n├── config.py              # pydantic-settings (.env)\n├── logger.py              # stderr-only logger (stdout is reserved for stdio MCP)\n├── client/\n│   ├── solver.py          # SolverClient — async wrapper over AsyncTwoCaptcha\n│   ├── pingback.py        # httpx wrapper for legacy res.php\n│   ├── rate_limiter.py    # async sliding-window per-method rate limiter\n│   └── errors.py          # internal CaptchaError hierarchy\n├── schemas/               # Pydantic request/response models per captcha family\n├── tools/                 # @captcha_tool handlers per captcha family + composite\n└── webhook_receiver/      # Starlette app + SQLite store (twocaptcha-mcp-webhook)\n```\n\nTool 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.\n\n## Webhook receiver (optional, since 0.3.0)\n\nFor long-running solves (recaptcha v3 up to 600 s), the polling-mode SDK call\nholds the MCP request slot for the entire duration. Run the optional\n`twocaptcha-mcp-webhook` server to flip into pingback mode — 2Captcha POSTs the\nresult to your URL, the receiver writes it to SQLite, and the MCP tools read\nasynchronously without blocking.\n\n- **Composite tool**: [`twocaptcha_solve_and_wait_pingback`](TROUBLESHOOTING.md#server-hangs-forever-on-a-solve_recaptcha-call)\n  sends the captcha and waits on the local store\n- **Read tools**: `twocaptcha_pingback_events_list/get/clear`\n- **Deployment**: [docs/DEPLOY-WEBHOOK.md](docs/DEPLOY-WEBHOOK.md)\n- **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md#webhook-receiver)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the dev loop, code conventions, and the SemVer policy for the MCP tool surface.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md). Vulnerabilities are reported privately via GitHub Security Advisory.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n<sub>Registry verification — `mcp-name: io.github.aruxojuyu665/twocaptcha-mcp`</sub>\n",
  "bytes": 8318,
  "sha": "f2857c1029904c97441c29a6382190c462bf1d2845841a56548ab168af36fccc",
  "repo_slug": "aruxojuyu665/2captcha-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aruxojuyu665_twocaptcha_mcp_f932b623/readme"
}