# 2Captcha MCP

Gives your agent the whole 2Captcha API: 31 captcha types, balance checks, reports and pingbacks. Handy when captcha solving has to happen inside code.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: 0-SOFT
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/0-SOFT/2Captcha-MCP
- Updated: 2026-07-20
- HTML: https://affpapa.org/en/nevibecode/mcp/2captcha-mcp

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

1. **Command 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

2. **Platform CLI**
```bash
claude mcp add 2captcha-mcp -- uvx twocaptcha-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from twocaptcha-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add 2captcha-mcp -- uvx twocaptcha-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from twocaptcha-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add 2captcha-mcp uvx twocaptcha-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from twocaptcha-mcp <command>

## When to use it
- 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
- 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.

## Similar
- [steel-reliability](https://affpapa.org/en/nevibecode/skills/steel-reliability.md) — skill · 432 installs
- [scrapeless-mcp-server](https://affpapa.org/en/nevibecode/mcp/scrapeless-mcp-server.md) — MCP server · ★ 170
- [Svipall](https://affpapa.org/en/nevibecode/mcp/svipall.md) — MCP server · ★ 20
- [browser-act](https://affpapa.org/en/nevibecode/skills/browser-act.md) — skill · 108300 installs
- [FrankenSurf](https://affpapa.org/en/nevibecode/mcp/frankensurf.md) — MCP server · ★ 102
- [EveryInfra](https://affpapa.org/en/nevibecode/mcp/everyinfra.md) — MCP server · ★ 80

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md