CaptchaNo

CaptchaNo MCP サーバー

CaptchaNo の公式 Model Context Protocol サーバーです。 AI エージェント（Claude、Cursor、VS Code Copilot、その他すべての MCP クライアント）が、ブラウザーまたは HTTP の自動化を実行しながら、reCAPTCHA v2 / v3 / Enterprise、Cloudflare Turnstile、DataDome、画像 CAPTCHA を解決できます。

解決処理は CaptchaNo 独自の解決インフラストラクチャで実行され、料金は CaptchaNo の残高から差し引かれます。 解決に失敗した場合、料金は一切発生しません。

許可された自動化にのみ使用してください。 CAPTCHA の解決は、自分が所有するサイト、自動化の許可を得ているサイト、または利用規約で許可されているサイトでのみ行ってください（自分のフォームの QA、アクセシビリティ、自分が所有するサイトのモニタリング、許可を得た調査など）。本ツールの使用方法については、利用者が責任を負います。

• ウェブサイト：https://captchano.com
• API ドキュメント：https://captchano.com/captcha-solver-api
• エージェントガイド：https://captchano.com/agents/mcp
• サポート：[email protected]

クイックスタート

1. https://captchano.com/dashboard で API キーを作成します。キーは cn- で始まります。
2. MCP クライアントにサーバーを追加します（以下の設定例を参照）。npx -y captchano-mcp で実行します。 Node.js 20.3 以降が必要です。
3. エージェントに 「サインアップページを開いて CAPTCHA を解決し、フォームを送信してください。」 のように依頼します。

Claude Code

claude mcp add captchano -e CAPTCHANO_API_KEY=cn-... -- npx -y captchano-mcp

すべてのプロジェクトで利用できるようにするには、--scope user を追加します。

Claude Desktop

claude_desktop_config.json を編集します（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "captchano": {
      "command": "npx",
      "args": ["-y", "captchano-mcp"],
      "env": {
        "CAPTCHANO_API_KEY": "cn-...",
        "CAPTCHANO_MAX_SPEND_USD": "1.00"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）：

{
  "mcpServers": {
    "captchano": {
      "command": "npx",
      "args": ["-y", "captchano-mcp"],
      "env": { "CAPTCHANO_API_KEY": "cn-..." }
    }
  }
}

VS Code（GitHub Copilot エージェントモード）

.vscode/mcp.json。VS Code は初回にキーの入力を求め、キーを安全に保存します：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "captchano-api-key",
      "description": "CaptchaNo API key (cn-...)",
      "password": true
    }
  ],
  "servers": {
    "captchano": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "captchano-mcp"],
      "env": { "CAPTCHANO_API_KEY": "${input:captchano-api-key}" }
    }
  }
}

Windsurf、Cline、Zed、その他のクライアント

上記と同じ command / args / env を使用します。command は npx、args は ["-y", "captchano-mcp"]、 env は CAPTCHANO_API_KEY です。

Docker

docker build -t captchano-mcp .
docker run -i --rm -e CAPTCHANO_API_KEY=cn-... captchano-mcp

設定

すべての設定は環境変数から読み込まれます。API キーをツールの引数として指定することはできません。

変数	必須	デフォルト	説明
CAPTCHANO_API_KEY	はい	–	API キー（cn-...）。
CAPTCHANO_MAX_SPEND_USD	いいえ	無制限	このサーバープロセスの USD 建て支出上限です。予算を参照してください。
CAPTCHANO_WAIT	いいえ	45	API が各解決リクエストをブロックする秒数（?wait=N、最大 120）です。この時間を過ぎると、サーバーはポーリングに切り替えます。
CAPTCHANO_TOOL_TIMEOUT	いいえ	50	solve_captcha の呼び出しが再開可能な solving 結果を返すまでの最大秒数です。多くの MCP クライアントは 60 秒でツール呼び出しをキャンセルします。クライアントがより長い時間を許容する場合にのみ、この値を増やしてください。
CAPTCHANO_API_BASE	いいえ	https://api.captchano.com	API のベース URL です。
CAPTCHANO_MCP_HTTP_TOKEN	いいえ	–	--http モードでは、/mcp に対する Authorization: Bearer <token> を必須にします。
CAPTCHANO_LOG_LEVEL	いいえ	info	debug、info、warn、error、silent のいずれかです。ログは stderr のみに出力されます。

ツール

solve_captcha

CAPTCHA を解決し、ページが必要とする値を返します。解決に成功した場合に課金されます。

引数	タイプ	説明
type	すべて	recaptcha_v2、recaptcha_v3、recaptcha_enterprise、turnstile、datadome、image
url	image 以外すべて	CAPTCHA が表示されているページの完全な URL
sitekey	recaptcha_*、turnstile	data-sitekey、k= iframe パラメーター、または render= スクリプトパラメーターから取得します
action	recaptcha_v3、recaptcha_enterprise、turnstile	ページで使用されるアクション名
minScore	recaptcha_v3	0.1～0.9
invisible	recaptcha_v2、recaptcha_enterprise	非表示ウィジェットの場合は true
cData、pageData	turnstile	data-cdata。Cloudflare のチャレンジページでは pageData
challengeUrl	datadome（必須）	ブロックされたレスポンスから取得した CAPTCHA の完全な URL
proxy	datadome（必須）、トークンタイプでは任意	"http://user:pass@host:port"（http、socks4、socks5）、または { scheme, host, port, username, password }
body	image（必須）	Base64 画像。data:image/...;base64, プレフィックスも使用できます
userAgent	image 以外すべて	解決結果を使用するクライアントの User-Agent

呼び出しの流れ：サーバーは POST /v1/solve?wait=N を送信します。API が 202（解決中）を返した場合、サーバーはデフォルトで最長合計 50 秒（CAPTCHANO_TOOL_TIMEOUT）、5 秒ごとに GET /v1/task/{id} をポーリングします。 その後もタスクが解決中の場合、結果には status: "solving" とタスク ID が含まれます。その場合、エージェントは再度解決を試みるのではなく、その ID を指定して get_task を呼び出してください。

結果はテキスト（トークン、Cookie またはテキスト、userAgent、cost、solveTime、次のステップ）と structuredContent として返されます：

{
  "id": "…",
  "type": "recaptcha_v2",
  "status": "ready",
  "token": "03AFcWeA…",
  "cost": "…",
  "solveTime": "…",
  "sessionSpend": { "spentUsd": "…", "limitUsd": "1.0000", "remainingUsd": "…" }
}

get_task

{ id } → 同じオブジェクトを返します。solving 状態の解決を再開する場合、または結果を再度読み取る場合に使用します。解決結果は 10 分間保持されます。読み取り専用で、無料です。

get_balance

{ balance, currency, sessionSpend } を返します。読み取り専用で、無料です。

list_captcha_types

サポートされているすべてのタイプの静的リストです。必須フィールドと任意フィールド、返される解決フィールド、ページ上で sitekey（またはその他の入力値）を見つける場所の簡単なヒントが含まれています。ネットワーク呼び出しは行いません。

エラー

API エラーは isError: true のツール結果として返されます。それぞれにエラーコード、API のメッセージ、次に行う操作のヒントが含まれています。例：

Error insufficient_balance: Insufficient balance
Hint: The CaptchaNo account has no balance left. Ask the user to top up at https://captchano.com/dashboard/topup, then retry. Failed solves are never billed.

API コード：invalid_api_key、insufficient_balance、unsupported_type、invalid_sitekey、proxy_required、proxy_unreachable、score_not_met、unsolvable、capacity_unavailable、rate_limited、task_not_found、upstream_error。 このサーバーのコード：invalid_arguments（リクエスト送信前に検出）、budget_exhausted、network_error、timeout、cancelled、http_error。

予算

CAPTCHANO_MAX_SPEND_USD を設定すると、1 つのサーバープロセスが使用できる金額に上限を設けられます。サーバーは、送信した各タスクについて API が返す cost を合計し、各タスクを 1 回だけ計上します。合計が上限に達すると、solve_captcha は API に接続せずに budget_exhausted を返します。get_task、get_balance、list_captcha_types は引き続き使用できます。

注意：

• 上限はプロセスごとに適用されます。サーバーまたは MCP クライアントを再起動するとリセットされます。アカウント全体に確実に上限を設定するには、キーの残高を少額に保ってください。
• 上限は解決を試みる前に確認されます。上限をわずかに下回った状態で開始した解決は、処理中の解決の費用分だけ上限を超えることがあります。

HTTP モード

CAPTCHANO_API_KEY=cn-... CAPTCHANO_MCP_HTTP_TOKEN=$(openssl rand -hex 24) \
  npx -y captchano-mcp --http --port 8080            # serves http://127.0.0.1:8080/mcp

• /mcp でステートレスな Streamable HTTP を提供し、GET /healthz も利用できます。
• デフォルトでは 127.0.0.1 にバインドします。--host 0.0.0.0 を使用するのは、TLS の背後で CAPTCHANO_MCP_HTTP_TOKEN を設定している場合に限ってください。このエンドポイントにアクセスできる人は誰でも残高を使用できます。
• キーは常にサーバーの環境から取得され、呼び出し元から渡されることはありません。

セキュリティ

• キー： CAPTCHANO_API_KEY は環境変数からのみ読み取られます。ツールの引数として渡されることも、ツールの結果に含まれることも、ログに記録されることもありません。ログ行からは、cn- キー、ベアラートークン、プロキシ認証情報らしきものも削除されます。
• stdout はプロトコルの通信チャネルです。 すべてのログは stderr に出力されます。
• 支出： solve_captcha が成功するたびに料金が発生します。自律型エージェントには、CAPTCHANO_MAX_SPEND_USD を設定し、残高の少ない専用キーを使用してください。このツールには、読み取り専用ではなく、オープンワールドのツールとして注釈が付けられているため、実行前に確認を求めるクライアントでは確認が求められます。
• プロキシ： プロキシ認証情報は HTTPS 経由で CaptchaNo API にのみ送信され、結果やログに再度含まれることはありません。
• プロンプトインジェクション： エージェントがアクセスしたページから、他のサイトの CAPTCHA を解かせようとする可能性があります。予期しない解決リクエストには人間が介在するようにし、支出上限を使用してください。
• 脆弱性は [email protected] まで報告してください。

開発

npm install
npm test          # unit tests (node:test, mocked fetch)
npm run e2e       # builds, then drives dist/ over stdio and HTTP with the official MCP client
npm run check     # typecheck + tests + build

npm run e2e は、実際の API に対してダミーキーで get_balance を呼び出し、適切な invalid_api_key の結果が返ることを確認します。CAPTCHANO_TEST_API_KEY が設定されている場合は、公開されている reCAPTCHA v2 デモでライブ解決を 1 回実行します。上限は $0.05 です。

ライセンス

MIT © DishIs Technologies LLC