Gemini CLI で MCP を使用して CAPTCHA ソルバー ツールを設定する方法

TL;DR

• Gemini CLI は、mcpServers 設定を通じてローカルの CAPTCHA ソルバーに接続できます。
• PATH の問題を避けるため、クライアントは Python 環境の実行ファイルを直接指定します。
• 有料の solve を承認済みワークフローで有効にする前に、まずツール検出から始めます。
• MCP サービスに接続できても、アカウントがチャレンジを解けることや、ブラウザフォームが完了したことの証明にはなりません。
• フォルダ信頼とツール承認は別の制御です。ツール実行時の確認は有効のままにしておきましょう。

Gemini CLI の CAPTCHA ソルバーセットアップは、ツール接続から始まります。ターミナルエージェントがブラウザテストや、その他許可された Web ワークフローの保守に役立つ場合、ソルバーは特定の CAPTCHA チェックポイントにのみ配置すべきです。通常のページ遷移、アプリケーション検証、エージェントにどの操作を許可するかの判断を置き換えるものではありません。

CapSolver は、Gemini CLI が検出できるローカル MCP サービスを提供します。本ガイドでは、公開されたインターフェースを使って両者を接続し、その接続を確認する方法と、その後どこに solving ツールを組み込むかを説明します。ここで紹介する実行可能なセットアップは macOS と Linux を対象としています。接続を確立するのに対象 Web サイトは不要であり、Gemini CLI が既にブラウザを制御していることも前提としていません。

CAPTCHA ソルバーは Gemini CLI に何を追加するのか？

CAPTCHA ソルバーは、周辺のワークフローが既に特定し、扱うことを許可されたチャレンジに対して、Gemini CLI に呼び出し可能な機能を提供します。Gemini CLI はサーバー設定を読み込み、利用可能なツールを提示します。MCP プロセスはツール定義を提供し、要求された処理を実行します。

自社アプリをテストする QA チームの場合、ブラウザテストはテストデータ入力後に CAPTCHA ウィジェットへ到達するかもしれません。ソルバーは、その時点でサポートされているチャレンジを処理できますが、フォーム入力およびアプリケーションが送信を受け付けたというアサーションは依然としてテスト側が保持します。MCP サービスをインストールしただけでは、こうしたブラウザ操作手順は構築されません。

Google はクライアント接続を MCP サーバー構成ガイドで文書化しています。CapSolver は対応する MCP サービスとツールの役割 を公開しています。両インターフェースはローカルの stdio プロセスで合流するので、初期検出に別途クライアントアダプタを用意する必要はありません。

接続前に必要なものは？

対応した Node.js ランタイム、Python、分離されたプロジェクトディレクトリ、および公式のクライアント・サーバーパッケージが必要です。本セットアップは Node.js 24.16.0、Python 3.12.14、Gemini CLI 0.65.0、capsolver-mcp 0.1.3 で検証されています。これらのバージョンは「テスト済みの組み合わせ」を示すものであり、永続的な固定を要求するものではありません。

公式の Gemini CLI インストール手順 でクライアントの前提条件が説明されています。Python 3.10 以降と、固定された Gemini パッケージがサポートする Node.js バージョンを使用してください。既存のエージェント環境を置き換えることなく接続テストを行えるよう、別の環境を用意します。

理解しておくべき認証情報は 2 種類あります。Gemini のモデル認証は、CLI が応答を生成できるようにするものです。CapSolver の API キー は、有料 solve などのアカウント操作を認可します。どちらも相互に代替はできません。以下の接続チェックでは CAPTCHA の送信もモデル応答の要求も行いません。後段の solving と会話的な利用には、それぞれのアカウント設定が必要です。

ローカルサーバーとクライアントのインストール

接続テストを行うディレクトリに公式パッケージをインストールします。新しい作業ディレクトリから Python 環境を作成し、固定バージョンのパッケージをインストールします。

python3 -m venv py
py/bin/python -m pip install capsolver-mcp==0.1.3
npm init -y
npm install --save-dev @google/gemini-cli@0.65.0

Python のインストールによってコア依存パッケージが導入されます。このガイドを後で再現する場合は、インストールされたバージョンを確認してください。依存関係の変更により、設定が同じでもツールや出力が変わる可能性があります。別のターミナルセッションからも確実に環境を特定できるよう、この環境をプロジェクトと紐づけておきましょう。

この接続にはベースの MCP パッケージだけで十分です。ブラウザ指向のツールには追加の依存関係が必要になります。初期接続を確立するだけなら、それらは不要です。公式レジストリのインストール手順 では公開パッケージとインストール方法が解説されています。

Gemini CLI に MCP サーバーを設定する

Gemini CLI が、作成した環境内の Python インタプリタを起動するよう設定します。このエントリを ~/.gemini/settings.json にある既存のユーザー設定へマージしてください。他の設定やサーバーは維持します。実行ファイルパスはプロジェクトの py/bin/python への絶対パスに置き換えてください。

{
  "mcpServers": {
    "capsolver": {
      "command": "/absolute/path/to/project/py/bin/python",
      "args": ["-m", "capsolver_mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "${CAPSOLVER_API_KEY}"
      },
      "includeTools": ["get_supported_captchas", "solve_captcha"],
      "trust": false,
      "timeout": 60000
    }
  }
}

絶対パスを使うことでよくあるセットアップ問題――シェルは環境を認識しているのに、クライアントが別の Python で起動してしまう――を回避できます。変数参照を使うことで、JSON ファイル内に生のアカウントキーを書かずに済みます。実際のキーは、アカウント操作を行う前に通常の秘密情報管理プロセスを通して注入してください。

このスターター設定は、機能問い合わせ用ツールとトークン指向の solving ツールを公開します。一方でブラウザ指向ツールは許可リストの外に置かれており、ブラウザセッションをどう管理するか検討する余地があります。timeout はミリ秒単位のクライアント設定であり、CAPTCHA 完了時間を保証するものではありません。

フォルダ信頼とサーバー信頼は分けて考える

Gemini CLI は、現在のフォルダが信頼されていない場合 MCP サーバーを無効化することがあります。自分が所有しレビュー済みのプロジェクトでは、Google の trusted-folder ワークフロー に従ってください。関係ないフォルダを変更するのではなく、意図したプロジェクト範囲を信頼対象にします。

サーバー側の trust: false は別の目的を持ちます。これはツール呼び出し時の確認動作を維持する設定です。作業ディレクトリを信頼済みにしたからといって、将来のすべてのツール呼び出しを自動承認すべきとは限りません。接続診断から実際のアプリケーションワークフローへ移行するときも、この区別を維持してください。

CapSolver ボーナスコードの利用

自動化用の予算を即座に増強しましょう。
入金時にボーナスコード CAP26 を使用すると、すべてのチャージに対して 5% のボーナス が無制限に付与されます。
今すぐ CapSolver ダッシュボード で引き換えてください。

solve を要求する前に接続を検証する

プロジェクトディレクトリから、Gemini CLI の MCP 一覧コマンドで設定したサービスを検証します。

npx --no-install gemini mcp list

成功したチェックでは、capsolver サーバーが stdio を使い、ステータスが Connected と表示されました。表示されるコマンドにはインタプリタのパスと -m capsolver_mcp が含まれます。絶対パスは環境ごとに異なります。Disabled と表示される場合は、設定または信頼の判定に問題がある可能性があります。接続が失敗する場合は、実行ファイルパスとプロセス起動を確認してください。

Gemini の通常の認証が済んだら、クライアントの MCP インターフェースからツールを確認します。最初のリクエストとして有用なのは、何も solve せずにサポートされている CAPTCHA タイプを問い合わせることです。意図されたツールは get_supported_captchas です。能力チェックだけが目的の場合は、アカウント残高照会や solve 要求に置き換えないでください。

検証範囲は厳密です。ローカルの Gemini CLI 接続が、実際の MCP プロセスに対して試行されただけです。モデル主導の会話、有料チャレンジ、ブラウザフォームの完了は、このチェックによって保証されません。これらは、構築するワークフローのために別途受け入れテストを行う必要があります。

ソルバーは明示的なブラウザチェックポイントに置く

solve 操作は、CAPTCHA の検出が確認されてから、次のアプリケーションレベル検証までの間に配置してください。所有者が管理するブラウザテストでは、想定される順序は次の通りです。テストフォームへ到達し、サポートされたチャレンジを特定し、適切な操作を要求し、文書化された結果を適用し、アプリケーションの応答を確認します。

トークン指向の solve_captcha ツールは、必要なチャレンジパラメータを既に把握し、それ以外のブラウザ作業を保持しているアプリケーションに適しています。呼び出しを行う前に、実際の入力スキーマを確認してください。古いチャレンジや、別環境の URL が有効になるわけではなく、クライアントが接続されていることとは無関係です。

CapSolver はブラウザベースツールとして detect_captchas と solve_on_page も公開しています。これらにはブラウザ用エクストラと Chromium が必要であり、そのセッション挙動がアプリケーションに適合している必要があります。URL ベースツールが、別のエージェントにより制御されている無関係なブラウザのクッキーやアクティブページを共有していると想定してはいけません。すでに自分のプログラムが所有するページを操作する必要がある場合は、別の統合ルートを選ぶ前に コア SDK のページ指向インターフェース を確認してください。

初回ロールアウトでは、承認済みテストワークフローを 1 つ選び、その完了シグナルを書き留めてください。フォームテストであれば、既知のテストデータ送信後に想定される確認状態が必要になるかもしれません。返されたトークンはソルバー操作に関する証跡であり、確認状態はアプリケーションに関する証跡です。資格情報や完全なトークンをログに残さないよう注意しつつ、両方をテスト結果として保持してください。

有料コールを繰り返さずにセットアップをトラブルシュートする

別のチャレンジを始める前に、失敗したステージを切り分けてください。実際の問題が Python パスや無効化された MCP サービスである場合、有料 solve を繰り返す必要はありません。

• プロセスが起動できない場合は、設定したインタプリタが存在し、その環境にパッケージがインストールされているか確認します。
• Gemini がサービスを disabled と表示する場合は、フォルダ信頼と、サーバーが明示的に無効化されていないかを確認します。
• サービスは接続できるがツールが見つからない場合は、許可リストや除外設定を、公開されている正確なツール名と比較します。
• アカウント操作が失敗する場合は、キーとアカウント要件を確認し、ツール検出を認証の証拠とみなさないでください。
• 結果は返ってくるがフォームが完了しない場合は、MCP トランスポートを変更する前に、結果の扱いとアプリケーション検証を点検してください。

1 回に 1 つだけ変更を加え、その変更を確認できる最も低コストなチェックを繰り返しましょう。アップグレード後は、古いプロンプトを再利用する前にツール名とスキーマを再検出してください。パッケージバージョン、サーバー名、ツール範囲を含む小さなセットアップ記録は、マスクされていない大量のリクエストログよりも有用であることがほとんどです。

接続済みツールからテスト済みワークフローへ移行する

ローカル接続と、意図したブラウザのハンドオフが明確になってから、実際の solve に進みます。承認されたタスクに対しては最も狭いツールスコープから始め、アプリケーションの最終状態は別途検証してください。CapSolver は CAPTCHA 処理を提供し、Gemini CLI はその周辺作業を調整する役割を果たせます。

CapSolver ダッシュボード を使って、その別個の solving テストに向けてアカウントを準備してください。クライアントやパッケージの変更後は、接続チェックを素早い診断として活用しましょう。

FAQ

Q: この設定後、Gemini CLI は自動的に CAPTCHA を解きますか？

いいえ。この設定は外部の MCP ツールプロバイダへ接続するだけです。周辺ワークフローには依然として有効な入力、承認済みの操作、アプリケーション結果のチェックが必要です。

Q: Connected と表示させるのに CapSolver API キーは必要ですか？

テストしたローカル接続は、アカウント操作なしで成功しました。有料 solve には有効なキーと該当するアカウント要件が必要です。Connected ステータスは、これらを検証するものではありません。

Q: 見慣れないフォルダで MCP サーバーが disabled になるのはなぜですか？

Gemini CLI のフォルダ信頼ポリシーにより、信頼されていないディレクトリでは MCP サーバーが抑制されることがあります。フォルダを確認し、意図した範囲に対してクライアントの信頼フローを実施してください。

Q: なぜ設定では 2 つのツールしか公開していないのですか？

例では、機能問い合わせ用ツールとトークン solving ツールだけを許可しています。他のツール、その依存関係、およびワークフローとの適合性を確認してから許可リストを変更してください。

Q: ページ solving ツールは既存のブラウザタブを再利用しますか？

そうだと想定してはいけません。文書化されたセッションモデルを確認してください。URL ベースの操作と、あなたのブラウザプログラムが所有するページオブジェクトは別のインターフェースです。

Q: MCP 接続が動作した後、何をテストすべきですか？

有効な資格情報と観測可能なアプリケーション結果を伴う、承認済みのエンドツーエンドワークフローを 1 つテストしてください。ソルバーのステータスとページの最終結果は、それぞれ別々に記録しましょう。