How do I install 2Captcha MCP?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does 2Captcha MCP need an API key?

The publisher lists these environment variables: 2Captcha_API_KEY.

What transport does 2Captcha MCP use?

2Captcha MCP runs locally over stdio.

When was 2Captcha MCP last checked?

Last checked 2026-11-09. Full 2Captcha API (43 tools) for Claude Code: 31 captcha solvers + management + webhook.

2Captcha MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx twocaptcha-mcp==0.6.1

Credentials from the publisher

2Captcha_API_KEY — 2Captcha account API key (https://2captcha.com/setting)

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

12Captcha_API_KEY=<secret> claude mcp add io.github.aruxojuyu665-twocaptcha-mcp -- uvx twocaptcha-mcp==0.6.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.aruxojuyu665-twocaptcha-mcp": {4      "command": "uvx",5      "args": [6        "twocaptcha-mcp==0.6.1"7      ],8      "env": {9        "2Captcha_API_KEY": "<secret>"10      }11    }12  }13}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.6.1
API key

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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)

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:

Setting	Aliases	Default	Range
API key (required)	`2Captcha_API_KEY`, `TWOCAPTCHA_API_KEY`, `2CAPTCHA_API_KEY`, `API_KEY_2CAPTCHA`	—	—
Server	`TWOCAPTCHA_SERVER`	`2captcha.com`	`2captcha.com`, `rucaptcha.com`
Default timeout	`TWOCAPTCHA_DEFAULT_TIMEOUT`	`120` s	1..600
reCAPTCHA timeout	`TWOCAPTCHA_RECAPTCHA_TIMEOUT`	`600` s	1..1200
Polling interval	`TWOCAPTCHA_POLLING_INTERVAL`	`10` s	1..120
Soft id	`TWOCAPTCHA_SOFT_ID`	`4580`	—
Log level	`TWOCAPTCHA_LOG_LEVEL`	`INFO`	DEBUG/INFO/WARNING/ERROR/CRITICAL
Default pingback URL	`TWOCAPTCHA_DEFAULT_CALLBACK`	unset	https URL

Tools

Captcha solvers (31)

Tool	SDK method	Required arguments
`twocaptcha_solve_normal`	`normal`	`file_path` xor `file_base64`
`twocaptcha_solve_text`	`text`	`text`
`twocaptcha_solve_audio`	`audio`	file (xor), `audio_lang`
`twocaptcha_solve_grid`	`grid`	file (xor)
`twocaptcha_solve_canvas`	`canvas`	file (xor)
`twocaptcha_solve_coordinates`	`coordinates`	file (xor)
`twocaptcha_solve_rotate`	`rotate`	`files: list`
`twocaptcha_solve_vkimage`	`vkimage`	`files`, `steps`
`twocaptcha_solve_recaptcha`	`recaptcha`	`sitekey`, `url`, `version`, `enterprise`
`twocaptcha_solve_hcaptcha`	`hcaptcha`	`sitekey`, `url`
`twocaptcha_solve_turnstile`	`turnstile`	`sitekey`, `url` (+ `data`/`pagedata` for CF Challenge)
`twocaptcha_solve_funcaptcha`	`funcaptcha`	`sitekey`, `url`
`twocaptcha_solve_geetest`	`geetest`	`gt`, `challenge`, `url`
`twocaptcha_solve_geetest_v4`	`geetest_v4`	,

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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install 2Captcha MCP?

Does 2Captcha MCP need an API key?

What transport does 2Captcha MCP use?

When was 2Captcha MCP last checked?

Documentation

2Captcha MCP

Quick start

Configuration

Tools

Captcha solvers (31)

Management (5)

Pingback CRUD (3)

Development

Architecture

Webhook receiver (optional, since 0.3.0)

Contributing

Security

License