2Captcha MCP

What 2Captcha MCP MCP server does

The 2Captcha MCP MCP server presents the 2Captcha API as MCP tools for agents that need to submit CAPTCHA-solving requests and retrieve results. It includes 31 solver tools covering image-based challenges, text and audio inputs, and web CAPTCHA families such as reCAPTCHA, hCaptcha, Turnstile, FunCaptcha, GeeTest, Amazon WAF, and Yandex Smart.

Beyond solving, the server exposes tools to check the current account balance, report a CAPTCHA result as good or bad, manually retrieve a result, and send raw requests for SDK functionality not represented by a dedicated tool. Pingback tools can register, list, and remove callback URLs. The README describes 43 tools in total, including webhook event-store operations and a composite solve-and-wait operation.

How it works

Requests arrive through the MCP stdio transport. The server validates tool inputs with typed schemas and passes solver calls through an asynchronous client built on the official 2captcha-python SDK. The SDK handles submission, polling, retries, and response parsing. Solver calls can accept optional proxy, pingback, soft ID, cookies, user-agent, language, and ACAO-header settings where applicable.

For long-running requests, the optional webhook mode changes the result flow. A separate receiver accepts 2Captcha POST callbacks, stores events in SQLite, and lets MCP tools read the results asynchronously. This can avoid holding an MCP request open for the full polling period.

The 2Captcha MCP MCP server is intended for environments that can run a Python module and provide environment-based configuration. The documented registration command uses Claude Code and starts the process with stdio.

Setup and configuration

Install the package with pip install twocaptcha-mcp. Provide an API key using one of the supported aliases; TWOCAPTCHA_API_KEY is an uppercase alias suitable for environment-based deployment. The canonical documented name is 2Captcha_API_KEY. Start the server with:

python -m twocaptcha_mcp

Optional settings select the API host, default and reCAPTCHA timeouts, polling interval, soft ID, log level, and default callback URL. The server supports 2captcha.com and rucaptcha.com as API hosts. Timeout and polling values are bounded by the ranges documented in the project configuration.

Tools and capabilities

• Solve normal image CAPTCHAs from a file path or base64 data.
• Submit text, audio, grid, canvas, coordinate, rotate, and VK image challenges.
• Solve supported site-key and token-based CAPTCHA types with their required page parameters.
• Pass proxies and per-request callback URLs to solver tools.
• Check balance, report results, poll IDs, and send raw SDK requests.
• Register and manage pingback addresses.
• Read, list, and clear webhook events when the optional receiver is deployed.

The exact required arguments vary by CAPTCHA type. For example, reCAPTCHA needs a site key, URL, version, and enterprise setting, while GeeTest uses its challenge-specific identifiers. Some solvers require proxy and user-agent values as part of the SDK signature.

Limitations and notes

An API key and an account with 2Captcha are required; solving requests may consume account credits, as indicated by the project’s live-test instructions. The server does not replace the target website’s integration logic: callers still need to supply the site keys, URLs, tokens, files, or other parameters required by each CAPTCHA family.

Pingback URLs must be registered before they are used for solver calls. The optional webhook receiver is a separate component, and deployment requires making its callback endpoint available to 2Captcha. The documented server interface is stdio-based, and the README specifically shows setup for Claude Code rather than listing other MCP clients.

The 2Captcha MCP MCP server is licensed under MIT. Its configuration supports a default polling mode, while the webhook path is useful when a solve may take long enough to block a normal MCP request.