Qwen CodeでCAPTCHA Solver MCPツールを設定する方法

要約

• Qwen Code は、公式の CapSolver MCP サービスにローカルの stdio プロセスとして接続できる。
• パッケージをインストールした環境の Python 実行ファイルを使って、そのサーバーをプロジェクトの .qwen/settings.json に記述する。
• プロジェクトのサーバー設定を確認して承認したあと、qwen mcp list を実行して接続を確認する。
• 接続が「Connected」であればツールは利用可能だが、有料 CAPTCHA リクエストやブラウザ送信が成功した証明にはならない。
• 明示的な CAPTCHA パラメータにはトークン系ツールを、サービス側で管理しているページにはブラウザ系ツールを使う。別々の MCP サーバー間でブラウザタブが自動共有されることはない。

Qwen Code はターミナル上で動作するオープンソースのコーディングエージェントであり、開発者はアプリケーションコードの作業や接続されたツールの呼び出しに利用できる。許可されたブラウザワークフローが CAPTCHA に到達した場合、コーディングモデル単体では CAPTCHA 解決結果を提供できない。ソルバーには、関連するチャレンジ入力と、その結果を書き戻す明確な宛先が必要になる。

CapSolver は、公式 MCP サービスを通じてこれらの機能を公開している。本ガイドでは、そのサービスを Qwen Code に接続し、クライアントから到達できることを確認し、適切なツールの選び方を説明する。ここでの接続例では、モデルに Python コードの即興生成や API ペイロードの創作をさせる必要はない。

Qwen Code 連携で提供されるもの

この連携により、Qwen Code は CAPTCHA 関連ツールを実装する別サービスへアクセスできるようになる。Qwen Code はツールを検出しアクションを要求するクライアントの役割を保ち、サービス側がドキュメント化されたソルバー処理を実行する。

公式 Qwen Code プロジェクトでは、Qwen Code はターミナル上のコーディングエージェントとして説明されている。MCP は、その環境をサーバー提供の機能で拡張する。CAPTCHA サーバーを導入しても、すべてのコーディングタスクがブラウザタスクに変わるわけではなく、通常のコード編集にソルバーは不要である。

有用なケースは、許可されたブラウザワークフローの次のステップが CAPTCHA によってブロックされている場合だ。開発者はチャレンジを確認し、サポートされている操作を選択し、その結果をそのページに紐づけたまま維持できる。これは、「エージェントにウェブサイト全体のアクセス性を保証させる」といった広範な要求よりも範囲が狭い。

ワークフローに MCP を初めて導入する場合、クライアントとAPI コールの違いが重要になる。ツール記述は操作内容を「告知」するに過ぎず、実際の呼び出しが操作を実行する。接続ステータスは「利用可能性」を示すだけであり、告知されたすべての操作が成功したことを意味しない。

クライアントと Python 環境の準備

プロジェクト設定を編集する前に、Qwen Code と公式サーバーを含む Python 環境を用意する。

ここで説明する接続は、Qwen Code 0.26.1 と capsolver-core 0.1.1、capsolver-mcp 0.1.3 を使用している。Qwen Code のパッケージは Node.js 22 以上が必要である。qwen コマンドが未インストールの場合は、公式インストール手順に従うこと。

ソルバーパッケージは、Qwen Code から起動させたい Python 環境にインストールする。

python -m pip install capsolver-core==0.1.1 capsolver-mcp==0.1.3

公式 MCP インストールガイドには、ブラウザ用 extra と Chromium のインストールについても記載がある。これらの依存関係はブラウザベースの検出およびページ解決に必要だが、stdio 接続の確立とは別物である。

有効な CapSolver API キーと十分なアカウント残高は、有料解決の前提条件となる。Qwen Code でのモデル利用権限も、対話的なツール利用における別個の前提条件だ。以下の接続確認ではサーバーの起動と接続のみをテストし、有料解決の送信やモデル駆動のタスク実行は行わない。

アカウントキーは Qwen Code を起動する環境に保持すること。実際の値を追跡対象のプロジェクト設定、記事、Issue、スクリーンショット、共有トランスクリプトなどに貼り付けないよう注意する。

プロジェクトにサーバーを設定する

プロジェクトルートの .qwen/settings.json にある mcpServers オブジェクトに capsolver エントリを追加する。

Qwen Code は、プロジェクト設定と環境変数置換の両方について、MCP セットアップリファレンスで説明している。既存の設定を置き換えるのではなく、他のサーバーやプロジェクト設定を保ったままエントリをマージする。

{
  "mcpServers": {
    "capsolver": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["-m", "capsolver_mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "${CAPSOLVER_API_KEY}"
      },
      "trust": false
    }
  }
}

実行ファイルのパスは、インストール済み環境内の実際の Python パスに置き換える。絶対パスを使うことで、ターミナルやエディタ、サービスランチャーが各自の検索パス経由で「別の」Python を見つけてしまうことを防げる。仮想環境のパス自体を保持し、ベースインタプリタへのシンボリックリンク解決によって、必要なパッケージが入っていないインタプリタが選択されないようにする。

プレースホルダは API キーそのものではなく、環境変数参照である。変数は Qwen Code が起動されるときのプロセス環境に存在していなければならない。あるターミナルで設定したキーが、別の場所から起動したクライアントに自動的に引き継がれることはない。

この設定は stdio を使用する。Qwen Code は Python モジュールをローカルプロセスとして起動する。公開 HTTP エンドポイントや、公開ポート、コンテンツ公開ワークフローで使われる CMS MCP 認証情報は不要である。

CapSolver ボーナスコードを利用する

自動化用の予算をすぐに底上げしましょう！
入金時にボーナスコード CAP26 を使用すると、毎回のチャージ額に対して追加で 5% のボーナス が無制限に付与されます。
今すぐ CapSolver ダッシュボード から引き換えてください。

実際の接続を承認して検証する

レビュー済みのプロジェクトサーバーを承認し、同じプロジェクトディレクトリから接続を確認する。

qwen mcp approve capsolver
qwen mcp list

テストしたクライアントバージョンでは、未承認のプロジェクトエントリは「保留中（pending）」として表示される。承認後にサーバーは接続可能になる。期待される有用なシグナルは、capsolver エントリが connected と表示されることだ。その行には実行ファイルとトランスポート種別も示される。

承認と trust は別の目的を持つ。レビュー済みサーバーの承認は、それを接続可能にする。一方で trust を false のままにしておけば、ツールコールの確認動作は通常どおり維持される。単に設定問題を隠したいだけで、その値を変更すべきではない。

接続に失敗した場合は、まず実行ファイルのパスを確認し、そのうえで同じ Python 環境でインストール済みパッケージが import できるかどうかを確かめる。また、設定が実際に開いているプロジェクトのものかも確認する。Qwen の設定リファレンスでは、設定の読み込み元が説明されており、別の場所に重複エントリがあるとトラブルシューティングを複雑にする可能性がある。

解決キーなしで接続に成功しても、それだけではアカウントアクセスが確立されたことにはならない。接続チェックと課金対象の操作は、システムの異なる部分を動作させる。

CAPTCHA ステップに合ったツールを選ぶ

すでに利用できている情報とブラウザ状態に合わせてツールを選択する。

公式サービスは get_supported_captchas、get_balance、detect_captchas、solve_captcha、solve_on_page を公開している。インストールしたサービスの対応 CAPTCHA 名を確認したいときは、まずサポート種別一覧から始める。アカウント側の準備状況を診断する場合は、残高確認を別途行う。

すでにワークフローで CAPTCHA タイプとサイトパラメータが分かっている場合は、solve_captcha を利用する。その結果は、要求元アプリケーションで消費される必要がある。トークンベースのタスクでは、トークンを受け取っただけではフォーム送信や、ウェブサイトによるリクエスト受理が保証されない点に注意する。

ブラウザツールは、ドキュメント化されたブラウザセットアップとともにのみ使用する。detect_captchas はページ URL を検査する。solve_on_page は、サービス側のブラウザワークフローの中で、検出・解決・ページへの書き戻しを組み合わせて行う。どちらの名前も、別の MCP サーバーが所有するタブへのアクセスを約束するものではない。

初回の対話的チェックとしては、設定済みサーバー経由で Qwen Code にサポート CAPTCHA タイプ一覧を問い合わせるとよい。許可されたページタスクでは、対象ページと許可された操作を明確に記述し、実行前に選択されたツールと引数を確認する。サイトにアクセスが許可されるまで「試行を続けよ」といったオープンエンドな指示は避ける。

ブラウザのハンドオフは明示的に行う

ブラウザのハンドオフでは、そのタスクに必要なコンテキストを保持しなければならない。URL だけでは、以前の操作を経由して到達したページを再現できない場合がある。

既存のブラウザ自動化がライブページを制御している場合、そのワークフローにトークンが必要なのか、それともそのページへの SDK 連携が必要なのかを判断する。MCP サーバーを 2 つ追加しただけで、セッション、クッキー、タブ、JavaScript 状態が自動的にマージされると想定してはならない。

Core SDK 連携ガイドでは、ブラウザへの直接統合が説明されている。アプリケーション側で既存のページオブジェクトを保持する必要がある場合には、こちらが適切なルートになり得る。トークンと Cookie の違いに関する解説も、ソルバーが返す成果物と、ブラウザセッション全体の状態を区別するのに役立つ。

ワークフローを完了とみなす前に、アプリケーション側の結果を確認すること。想定したフォームは受理されたか。許可されたページは意図した状態へ遷移したか。接続済みサーバー、検出されたウィジェット、受理されたアプリケーションリクエストは、いずれも別々のマイルストーンである。

CapSolver で信頼性の高い自動化ワークフローを構築する

公式サービスに接続し、ツールを確認し、まずは自分のワークフローに出てくる CAPTCHA に対応した、範囲が明確な 1 操作から始めよう。CapSolver はドキュメント化された解決ステップを提供し、Qwen Code は、あなたが承認したタスクの範囲内で、どのツールをどのように呼び出すかを引き続き担当する。

FAQ

Q: Qwen Code にはデフォルトで CAPTCHA ソルバーが含まれていますか？

いいえ。本ガイドでは、CapSolver 公式 MCP サービスを別個のツールプロバイダとして追加している。Qwen Code のモデルとソルバーアカウントは別コンポーネントである。

Q: サーバーが pending approval と表示されるのはなぜですか？

プロジェクトの MCP エントリは、Qwen Code が接続する前に承認を必要とすることがある。コマンドや環境設定を確認し、利用中のクライアントバージョンでサポートされる承認コマンドを実行する。

Q: CAPTCHA に料金を支払わずに接続テストはできますか？

はい。サーバー接続は、有料解決とは別に確認できる。接続済みステータスは、アカウント残高、有料タスクの実行、ウェブサイトによる解決結果の受理を検証するものではない。

Q: このサービスは他の MCP のブラウザタブを利用しますか？

そうであると想定してはならない。別々のサーバーは、明示的な連携がない限り、それぞれ独立したブラウザワークフローを持つ。既存ページの状態を保持する必要がある場合は、トークンモードか直接 SDK 連携を選択する。

Q: インストール後にブラウザツールが利用できないのはなぜですか？

公式 MCP ガイドにあるブラウザ extra と Chromium の前提条件を確認する。また、クライアント側のツールフィルタや、期待しているサーバーエントリが接続済みかどうかもチェックする。

Q: このセットアップであらゆるページ上のあらゆる CAPTCHA に対応できますか？

いいえ。最新のサポート種別一覧とタスクリファレンスを確認し、自動化が許可されているページとワークフローの範囲に操作を限定すること。ツールが「広告」されているからといって、任意のページでの成功が保証されるわけではない。