GeoIPプロキシの照合¶

GeoIPプロキシのマッチング機能により、ブラウザのフィンガープリント設定が、 上流のPlaywright MCPで使用されているプロキシの所在地と整合するようになります。これは、地域ごとのQAにおいて、 一貫したプロキシ、タイムゾーン、言語、ロケールプロファイルが求められる場合に役立ちます。

このブリッジ自体は、プロキシトラフィックを作成したりルーティングしたりすることはありません。プロキシのルーティングは、 PLAYWRIGHT_MCP_PROXY_SERVER を通じて、上流の Playwright MCP が引き続き管理します。 マッチングが 有効になっている場合、CloakBrowser MCP は設定されたプロキシのロケーションを解決し、 タイムゾーン、ブラウザの言語、および フィンガープリントのロケールに合わせて、CloakBrowser の起動フラグを追加します。

変更点¶

CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=trueの場合、ブリッジはCloakBrowserに対して以下の 起動フラグを追加できます：

• --fingerprint-timezone
• --lang
• --fingerprint-locale

これにより、ブラウザプロファイルがプロキシリージョンと内部的に整合性を持つようになります。 上流のPlaywright MCPツールのスキーマおよびブラウザツールは、 引き続き変更なしで転送されます。

グローバル設定¶

stdio クライアントではプロセスレベルの環境変数を使用し、 Streamable HTTP セッションのデフォルトとしてもこれを使用します：

PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
npx -y cloakbrowser-mcp@latest

特定のホストがプロキシを経由しないようにするには、バイパスリストを追加します：

PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
PLAYWRIGHT_MCP_PROXY_BYPASS=".internal,localhost" \
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
npx -y cloakbrowser-mcp@latest

認証済みHTTPプロキシは、認証情報を PLAYWRIGHT_MCP_PROXY_SERVER。認証情報に含まれる特殊文字をパーセントエンコードし、 たとえば、p%40ssword を p@ssword の代わりに使用します。

Docker のセットアップ¶

同じ変数をコンテナに渡してください。プロキシの認証情報は、可能な限りシークレット マネージャーまたはMCPクライアント環境に保管してください。

docker run --rm --init -i \
  -e PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
  -e CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

Docker での Streamable HTTP については、通常通り HTTP ポートを公開し、プロキシ 変数はコンテナ環境のデフォルト設定のままにします：

docker run --rm --init -p 127.0.0.1:3000:3000 \
  -e PLAYWRIGHT_MCP_PROXY_SERVER="http://user:pass@proxy.example:8080" \
  -e CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000

セッションごとのストリーミング対応HTTPプロキシ¶

ストリーム対応のHTTPクライアントは、MCPセッションの初期化時にプロキシを選択できます。 これにより、1つの長時間稼働するMCPサーバーが、再起動することなく、 さまざまな地域ごとのシナリオに対応できるようになります。

initialize リクエストでブリッジのメタデータを送信します：

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "proxyServer": "http://user:pass@proxy.example:8080",
        "proxyBypass": ".internal,localhost",
        "geoipProxyMatch": true
      }
    }
  }
}

proxyServer は、その HTTP セッションにおいて PLAYWRIGHT_MCP_PROXY_SERVER よりも優先されます。 proxyBypass は、PLAYWRIGHT_MCP_PROXY_BYPASS よりも優先されます。ただし、proxyServer が 存在する場合に限ります。proxyServerが存在し、かつproxyBypassが省略されている場合、そのセッションの継承された プロキシバイパス設定はクリアされます。

geoipProxyMatch は、その HTTP セッションにおけるプロセスレベルの GeoIP 設定を上書きします。true を使用すると、そのセッションのマッチングを有効にできます。また、false を使用すると、 サーバーがマッチングを有効にして起動された場合でも、マッチングを無効にできます。

既存のHTTPセッションは変更できません。別のプロキシやロケーションに切り替えるには、 別のStreamable HTTPセッションを作成してください。

proxyServer に認証情報が含まれている場合は、それらを URL エンコードした状態で保持し、その値を プロジェクトファイルにコミットするのではなく、シークレットやクライアントの実行時設定を通じて 渡してください。

ユースケース¶

優先順位と制限¶

GeoIPの位置情報は概算であり、プロキシのIPアドレスおよびCloakBrowserの GeoIPデータベースに依存します。CloakBrowserは、初回 使用時に必要に応じて、そのオフラインデータベースをダウンロードしてキャッシュします。

この機能は、正当な品質保証（QA）、ローカライズ、および環境の一貫性 テストのために使用してください。アクセス制御や地域 ポリシーのチェックを回避する手段として扱ってはなりません。

関連する設定¶

• 設定 には、すべてのブリッジおよびアップストリームの環境変数が記載されています。
• Docker では、コンテナランタイムのデフォルト設定と Streamable HTTP パブリッシングについて解説しています。
• ツール では、アップストリームの Playwright MCP ブラウザツールが変更されずに転送される理由について説明しています。

追加の実用パス¶

upstream Playwright MCP とこのパッケージのどちらを使うかは比較を参照してください。短い作業手順にはレシピを使います: 永続プロファイル、拡張機能、reverse proxy、リージョン QA、Claude Desktop、Codex CLI、CI スモークテスト。