2Captcha MCP — Claude Code MCP server: 43 captcha tools
Gives your agent the whole 2Captcha API: 31 captcha types, balance checks, reports and pingbacks. Handy when captcha solving has to happen inside code.
Open on GitHubWhat 2Captcha MCP does
The server speaks stdio and sits on top of the official 2captcha-python SDK (AsyncTwoCaptcha). Retries, result polling and response parsing stay in the SDK, so a captcha type shows up here as soon as the SDK ships it. There are 43 tools in all: 31 solvers, 5 management tools, 3 pingback tools, 3 webhook event-store tools and one composite solve-and-wait tool.
Management covers the everyday calls. twocaptcha_balance returns the account balance in USD, twocaptcha_report_good and twocaptcha_report_bad file a report against a captcha id, and twocaptcha_send_raw is the escape hatch for SDK methods the server does not expose yet. Configuration is environment-driven: the API key is required, the server defaults to 2captcha.com with rucaptcha.com as the alternative, the default timeout is 120 seconds, reCAPTCHA gets 600, and polling runs every 10 seconds.
No API key, no server — put it in .env as 2Captcha_API_KEY or pass it at registration time. Three solvers, datadome, captchafox and vkcaptcha, need proxy and user_agent in the call itself; the SDK signature rejects them otherwise. A captcha report is only accepted within 15 minutes of solving.
What it helps with
- solve a reCAPTCHA or Turnstile from a sitekey and page URL
- read text off an image and hand the answer to the agent
- check the 2Captcha balance before a scraping run
- file a report when a solved captcha came back wrong
- register and remove pingback URLs for automatic results
Example prompts for the agent
- Check my balance with
twocaptcha_balance. - Solve the reCAPTCHA on this page — I'll give you the sitekey and url.
- Register a pingback for our callback address.
How to install 2Captcha MCP
1Command from the source
We do not print this source command: it contains shell control characters. Take it from the repository README and read it first
2Platform CLI
claude mcp add 2captcha-mcp -- uvx twocaptcha-mcpuvx runs the command named after the package; if the README names another one, use uvx --from twocaptcha-mcp <command>
Platform CLI
codex mcp add 2captcha-mcp -- uvx twocaptcha-mcpuvx runs the command named after the package; if the README names another one, use uvx --from twocaptcha-mcp <command>
Config file
{
"mcpServers": {
"2captcha-mcp": {
"command": "uvx",
"args": [
"twocaptcha-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from twocaptcha-mcp <command>
Config file
{
"servers": {
"2captcha-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"twocaptcha-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from twocaptcha-mcp <command>
Platform CLI
gemini mcp add 2captcha-mcp uvx twocaptcha-mcpuvx runs the command named after the package; if the README names another one, use uvx --from twocaptcha-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about 2Captcha MCP
How do I install 2Captcha MCP in Claude Code?
Run claude mcp add 2captcha-mcp -- uvx twocaptcha-mcp. Restart claude and the server is picked up.
What does 2Captcha MCP do?
It exposes the 2Captcha API to your agent: 31 captcha solvers, balance and report management, pingback and webhook handling. That adds up to 43 tools.
What does the server need to run?
A 2Captcha key in 2Captcha_API_KEY and Python 3.11+. For datadome, captchafox and vkcaptcha, proxy and user_agent are required in the call.
