2Captcha MCP

2Captcha MCP

2Captcha API の全機能を公開する MCP サーバーです。Claude Code から stdio 経由で、31 種類の CAPTCHA、5 つの管理ツール、3 つの pingback CRUD ツール、3 つの Webhook イベントストアツール、1 つの解決・待機をまとめたツール（合計 43 ツール）を利用できます。

公式の 2captcha-python SDK（AsyncTwoCaptcha）を基盤としているため、再試行、ポーリング、解析は SDK 側で処理され、SDK が対応する CAPTCHA の種類は、SDK に追加されるとすぐに利用できます。

クイックスタート

pip install twocaptcha-mcp
# or for development:
pip install -e ".[dev]"

プロジェクトのルートディレクトリの隣に .env を作成します。

2Captcha_API_KEY=your_2captcha_key_here

動作を確認します。

python -m twocaptcha_mcp           # starts the stdio server (Ctrl+C to stop)

Claude Code にサーバーを登録します。

claude mcp add 2captcha -e 2Captcha_API_KEY=your_2captcha_key_here -- python -m twocaptcha_mcp

claude を再起動した後、次のようにモデルにプロンプトを入力します。

「twocaptcha_balance を使って、自分のアカウントを確認してください。」

設定

すべての設定は環境変数で指定します。エイリアスは優先順位の高い順に記載しています。

設定	エイリアス	デフォルト	範囲
API キー（必須）	2Captcha_API_KEY、TWOCAPTCHA_API_KEY、2CAPTCHA_API_KEY、API_KEY_2CAPTCHA	—	—
サーバー	TWOCAPTCHA_SERVER	2captcha.com	2captcha.com、rucaptcha.com
デフォルトのタイムアウト	TWOCAPTCHA_DEFAULT_TIMEOUT	120 s	1..600
reCAPTCHA のタイムアウト	TWOCAPTCHA_RECAPTCHA_TIMEOUT	600 s	1..1200
ポーリング間隔	TWOCAPTCHA_POLLING_INTERVAL	10 s	1..120
ソフト ID	TWOCAPTCHA_SOFT_ID	4580	—
ログレベル	TWOCAPTCHA_LOG_LEVEL	INFO	DEBUG/INFO/WARNING/ERROR/CRITICAL
デフォルトの pingback URL	TWOCAPTCHA_DEFAULT_CALLBACK	未設定	HTTPS URL

ツール

CAPTCHA ソルバー（31）

ツール	SDK メソッド	必須の引数
twocaptcha_solve_normal	normal	file_path と file_base64 のいずれか
twocaptcha_solve_text	text	text
twocaptcha_solve_audio	audio	file（いずれか）、audio_lang
twocaptcha_solve_grid	grid	file（いずれか）
twocaptcha_solve_canvas	canvas	file（いずれか）
twocaptcha_solve_coordinates	coordinates	file（いずれか）
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（CF Challenge の場合は data/pagedata も必要）
twocaptcha_solve_funcaptcha	funcaptcha	sitekey、url
twocaptcha_solve_geetest	geetest	gt、challenge、url
twocaptcha_solve_geetest_v4	geetest_v4	captcha_id、url
twocaptcha_solve_capy	capy	sitekey、url
twocaptcha_solve_keycaptcha	keycaptcha	s_s_c_user_id、s_s_c_session_id、2 つの署名、url
twocaptcha_solve_lemin	lemin	captcha_id、div_id、url
twocaptcha_solve_mtcaptcha	mtcaptcha	sitekey、url
twocaptcha_solve_friendly_captcha	friendly_captcha	sitekey、url
twocaptcha_solve_cutcaptcha	cutcaptcha	misery_key、apikey、url
twocaptcha_solve_amazon_waf	amazon_waf	sitekey、iv、context、url
twocaptcha_solve_tencent	tencent	app_id、url
twocaptcha_solve_atb_captcha	atb_captcha	app_id、api_server、url
twocaptcha_solve_datadome ⚑	datadome	proxy、user_agent、captcha_url、pageurl
twocaptcha_solve_captchafox ⚑	captchafox	proxy、user_agent、sitekey、pageurl
twocaptcha_solve_vkcaptcha ⚑	vkcaptcha	proxy、user_agent、redirect_uri
twocaptcha_solve_prosopo	prosopo	sitekey、pageurl
twocaptcha_solve_temu	temu	body、part1..3
twocaptcha_solve_altcha	altcha	pageurl
twocaptcha_solve_cybersiara	cybersiara	master_url_id、pageurl、cyber_user_agent
twocaptcha_solve_yandex_smart	yandex_smart	sitekey、url

⚑ — proxy と user_agent は SDK のシグネチャで必須です。

すべてのソルバーツールは、同じ任意の kwargs セット（mixin SolverKwargs）を受け付けます。

• proxy: {type, uri}（HTTP/HTTPS/SOCKS4/SOCKS5）
• pingback: HttpUrl — 呼び出しごとの pingback URL（事前登録が必要です）
• soft_id: int
• cookies: str
• user_agent: str
• lang: str
• header_acao: 0|1

管理（5）

• twocaptcha_balance — 現在の残高（USD）
• twocaptcha_report_good / twocaptcha_report_bad — 15 分以内に CAPTCHA ID を報告します
• twocaptcha_get_result — CAPTCHA ID を手動でポーリングします（send_raw と組み合わせて使用）
• twocaptcha_send_raw — このサーバーでまだ公開されていない SDK メソッドを使用するためのエスケープハッチ

Pingback CRUD（3）

• twocaptcha_register_pingback — コールバック URL を許可リストに登録します
• twocaptcha_list_pingbacks — 許可リストのアドレスを一覧表示します
• twocaptcha_delete_pingback — 1 件削除するか、addr="all" を指定してすべて削除します

開発

pytest --cov=twocaptcha_mcp --cov-branch --cov-fail-under=92 -v
ruff check . && ruff format --check .
mypy --strict twocaptcha_mcp

実際の 2Captcha API に対してライブテストを実行します（クレジットを消費します）。

pytest -m live --run-live          # balance + solve_normal + concurrent_balance
pytest -m e2e --run-e2e             # full MCP protocol roundtrip via mcp.client.session

アーキテクチャ

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)

ツールハンドラーは SolverClient / PingbackClient 抽象化のみに依存しており、SDK をハンドラーからインポートすることはありません。新しい CAPTCHA タイプの追加は、スキーマ → ツールハンドラー → スナップショットテストの件数更新、という 3 ステップの作業です。

Webhook 受信サーバー（任意、0.3.0 以降）

長時間実行される solve（recaptcha v3 は最大 600 s）では、ポーリングモードの SDK 呼び出しが実行中ずっと MCP リクエスト枠を占有します。任意の twocaptcha-mcp-webhook サーバーを実行して、ピンバックモードに切り替えます。2Captcha が結果を指定した URL に POST し、受信サーバーが SQLite に書き込みます。MCP ツールはブロックされることなく、非同期で結果を読み取ります。

• 複合ツール：twocaptcha_solve_and_wait_pingback は CAPTCHA を送信し、ローカルストアで結果を待ちます
• 読み取りツール：twocaptcha_pingback_events_list/get/clear
• デプロイ：docs/DEPLOY-WEBHOOK.md
• トラブルシューティング：TROUBLESHOOTING.md

コントリビューション

開発ループ、コード規約、MCP ツールのインターフェースに関する SemVer ポリシーについては、CONTRIBUTING.md をご覧ください。

セキュリティ

SECURITY.md をご覧ください。脆弱性は GitHub Security Advisory を通じて非公開で報告してください。

ライセンス

MIT — LICENSE をご覧ください。

---

_{レジストリの検証 — mcp-name: io.github.aruxojuyu665/twocaptcha-mcp}