Proxy MCP

🚀 proxy-mcp

proxy-mcpは、明示的なHTTP/HTTPS MITMプロキシ（L7）を実行するMCPサーバーです。リクエスト/レスポンスをキャプチャし、飛行中のトラフィック（ヘッダー/ボディ/モック/転送/ドロップ）を変更でき、上流プロキシのチェーンをサポートし、プロキシへの接続のTLSフィンガープリント（JA3/JA4）とオプションの上流サーバーのJA3Sを記録します。また、Chrome、CLIツール、Dockerコンテナ、Androidデバイス/アプリをプロキシ経由でルーティングする「インターセプター」も搭載しています。

81のツール + 8つのリソース + 4つのリソーステンプレート。mockttpをベースに構築されています。

制限事項

• このプロキシを経由するように設定されたトラフィックのみを確認できます（ネットワークタップやパケットスニッファーではありません）
• 送信するJA3 + HTTP/2フィンガープリント + ヘッダー順序を偽装します（Docker/Podman内のcurl-impersonateを介して）が、JA4は偽装しません（JA4はキャプチャのみ）
• HTTPヘッダーを追加、上書き、または削除できます。送信するヘッダーの順序は、フィンガープリントの偽装を介して制御できます
• 独自のCA証明書を返します。上流サーバーの証明書チェーンを公開しません

CDP/Playwrightとの相性

CDP/Playwrightをブラウザの内部（DOM、JS実行、localStorage、クッキージャー）に使用し、proxy-mcpをワイヤーレベルのキャプチャ/操作 + リプレイに使用します。両者は相補的です。

典型的なコンボは、interceptor_chrome_launchを介してChromeを起動し（自動的にプロキシを経由するようにルーティングされます）、Playwright/CDPでページを操作し、proxy-mcpを使用してワイヤートラフィックをキャプチャ、ヘッダーを注入、またはJA3を偽装することです — すべて同じセッション内で行います。行動のリアリズムのために、Playwrightの即時のpage.click()/page.type()の代わりにhumanizer_*ツールを使用します — これらは自然なタイミングカーブで人間らしいCDPのInput.*イベントをディスパッチします。

Playwrightをプロキシで起動されたChromeにアタッチするには：

1. proxy_startを呼び出します
2. interceptor_chrome_launchを呼び出します
3. proxy://chrome/primaryを読み取る（またはinterceptor_chrome_cdp_infoを呼び出す）ことで、cdp.httpUrl（Playwright用）とcdp.browserWebSocketDebuggerUrl（生のCDPクライアント用）を取得します
4. Playwrightでは、以下のようにします：

   import { chromium } from "playwright";
   const browser = await chromium.connectOverCDP("http://127.0.0.1:<cdp-port>");
   

プロキシに安全な組み込みCDPフロー（単一インスタンスで安全）：

1. proxy_startを呼び出します
2. interceptor_chrome_launchを呼び出します
3. そのtarget_idでinterceptor_chrome_devtools_attachを呼び出します
4. devtools_session_idでinterceptor_chrome_devtools_navigateを呼び出します
5. proxy_search_traffic --query "<hostname>"を呼び出してキャプチャを確認します

人間らしい入力フロー（ボット検出を回避）：

1. proxy_startを呼び出します
2. オプションでフィンガープリントの偽装を有効にします：proxy_set_fingerprint_spoof --preset chrome_136
3. interceptor_chrome_launch --url "https://example.com"を呼び出します（偽装時にはステルスモードが自動的に有効になります）
4. target_idを使用してhumanizer_move / humanizer_click / humanizer_type / humanizer_scrollを使用します
5. アクション間でhumanizer_idleを使用して自然な存在を維持します

🚀 クイックスタート

HTTPプロキシの設定

1) プロキシを起動し、エンドポイントを取得する

proxy_start

返されたportとエンドポイントhttp://127.0.0.1:<port>を使用します。

2) ブラウザの設定（推奨：インターセプター）

Chromeインターセプターを使用すると、プロキシフラグと証明書の信頼が自動的に設定されます。

interceptor_chrome_launch --url "https://example.com"

次に、同じターゲットにDevToolsを安全にバインドします。

interceptor_chrome_devtools_attach --target_id "chrome_<pid>"
interceptor_chrome_devtools_navigate --devtools_session_id "devtools_<id>" --url "https://apify.com"

3) ブラウザの設定（手動の代替手段）

Chromeを手動で起動する場合は、自分でプロキシフラグを渡します。

google-chrome --proxy-server="http://127.0.0.1:<port>"

4) CLI/プロセスの設定

プロキシ環境変数を設定することで、任意のプロセスをproxy-mcp経由でルーティングします。

export HTTP_PROXY="http://127.0.0.1:<port>"
export HTTPS_PROXY="http://127.0.0.1:<port>"
export NO_PROXY="localhost,127.0.0.1"

クライアントがTLSを検証する場合、proxy-mcpのCA証明書を信頼する（proxy_get_ca_certを参照）か、ターミナルインターセプター（interceptor_spawn）を使用します。これは、プロキシ環境変数と共通のCA環境変数（curl、Node、Python requests、Git、npm/yarnなど）を設定します。

interceptor_spawn --command curl --args '["-s","https://example.com"]'

明示的なcurlの例：

curl --proxy http://127.0.0.1:<port> http://example.com
curl --proxy http://127.0.0.1:<port> https://example.com

5) 上流プロキシのチェーン

proxy-mcpから別の上流プロキシへのオプションのプロキシチェーンを設定します（地理的位置、認証、またはIP評判のため）。

クライアント/アプリ  →  proxy-mcp（ローカルの明示的なプロキシ）  →  上流プロキシ（オプションのチェーン層）

proxy_set_upstream --proxy_url "socks5://user:pass@upstream.example:1080"

サポートされる上流URLスキーム：socks4://、socks5://、http://、https://、pac+http://。

典型的な地理的ルーティングの例：

# proxy-mcpからのすべての送信トラフィックを地理的プロキシ経由でルーティングする
proxy_set_upstream --proxy_url "socks5://user:pass@fr-exit.example.net:1080"

# ローカル/内部ホストに対して上流をバイパスする
proxy_set_upstream --proxy_url "http://user:pass@proxy.example.net:8080" --no_proxy '["localhost","127.0.0.1",".corp.local"]'

# 特定のホスト名のみを専用の上流経由でルーティングする（グローバル設定を上書きする）
proxy_set_host_upstream --hostname "api.example.com" --proxy_url "https://user:pass@us-exit.example.net:443"

# 終了後に上書きを削除する
proxy_remove_host_upstream --hostname "api.example.com"
proxy_clear_upstream

HTTPS MITMの場合、プロキシのCA証明書はターゲット環境で信頼されている必要があります（proxy_get_ca_cert）。

6) 迅速に検証し、トラブルシューティングする

proxy_list_traffic --limit 20
proxy_search_traffic --query "example.com"

一般的な問題：

• 誤ったブラウザインスタンスからのトラフィック（解決策：interceptor_chrome_devtools_attachを使用する）
• ターゲットでHTTPS証明書の信頼が不足している
• NO_PROXYが予期されるホストをバイパスしている
• chrome-devtools-mcpがインストールされていない（ENOENT）：interceptor_chrome_devtools_attachはナビゲーションのみのモードにフォールバックします。完全なスナップショット/ネットワーク/コンソール/スクリーンショットのサポートを得るには、chrome-devtools-mcpをインストールしてください。

MCPから直接サイドカーをプル/インストールします。

interceptor_chrome_devtools_pull_sidecar --version "0.2.2"

7) HARのインポート + リプレイ

HARを永続的なセッションにインポートし、既存のセッションクエリ/調査ツールで分析します。

proxy_import_har --har_file "/path/to/capture.har" --session_name "imported-run"
proxy_list_sessions
proxy_query_session --session_id SESSION_ID --hostname_contains "api.example.com"
proxy_get_session_handshakes --session_id SESSION_ID

リプレイはデフォルトでドライラン（プレビューのみ）です。実行するには明示的なモードが必要です。

# リプレイされる内容をプレビューする
proxy_replay_session --session_id SESSION_ID --mode dry_run --limit 20

# 元のホストに対してリプレイを実行する
proxy_replay_session --session_id SESSION_ID --mode execute --limit 20

# オプション：パス+クエリを保持しながらターゲットホスト/ベースURLを上書きする
proxy_replay_session --session_id SESSION_ID --mode execute --target_base_url "http://127.0.0.1:8081"

注：インポートされたHARエントリ（およびproxy_replay_sessionによって作成されたエントリ）にはJA3/JA4/JA3Sハンドシェイクメタデータが含まれていません。ハンドシェイクフィンガープリントを分析するには、ライブのプロキシキャプチャトラフィックを使用してください。

セットアップ

前提条件

• Node.js 22+
• DockerまたはPodman（TLSフィンガープリントの偽装に必要）

インストールとビルド

npm install
npm run build

実行

# stdioトランスポート（デフォルト） — Claude CodeなどのMCPクライアントで使用
node dist/index.js

# ストリーミング可能なHTTPトランスポート — /mcpエンドポイントを公開
node dist/index.js --transport http --port 3001

--transportと--portは、環境変数TRANSPORTとPORTも受け入れます。

グローバルインストール（オプション）

npm install -g .

これにより、proxy-mcpコマンドがシステム全体で使用可能になります（package.jsonのbinを参照）。

Claude Codeの.mcp.json

stdioトランスポート（デフォルト）：

{
  "mcpServers": {
    "proxy": {
      "command": "node",
      "args": ["/path/to/proxy-mcp/dist/index.js"]
    }
  }
}

グローバルにインストールされている場合は、proxy-mcpコマンドを直接使用できます。

{
  "mcpServers": {
    "proxy": {
      "command": "proxy-mcp"
    }
  }
}

ストリーミング可能なHTTPトランスポート：

{
  "mcpServers": {
    "proxy": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

✨ 主な機能

• 明示的なHTTP/HTTPS MITMプロキシ（L7）を実行し、リクエスト/レスポンスをキャプチャする
• 飛行中のトラフィック（ヘッダー/ボディ/モック/転送/ドロップ）を変更できる
• 上流プロキシのチェーンをサポートする
• TLSフィンガープリント（JA3/JA4）とオプションの上流サーバーのJA3Sを記録する
• Chrome、CLIツール、Dockerコンテナ、Androidデバイス/アプリをプロキシ経由でルーティングする「インターセプター」を搭載

📦 インストール

前提条件

• Node.js 22+
• DockerまたはPodman（TLSフィンガープリントの偽装に必要）

インストールとビルド

npm install
npm run build

実行

# stdioトランスポート（デフォルト） — Claude CodeなどのMCPクライアントで使用
node dist/index.js

# ストリーミング可能なHTTPトランスポート — /mcpエンドポイントを公開
node dist/index.js --transport http --port 3001

--transportと--portは、環境変数TRANSPORTとPORTも受け入れます。

グローバルインストール（オプション）

npm install -g .

これにより、proxy-mcpコマンドがシステム全体で使用可能になります（package.jsonのbinを参照）。

💻 使用例

基本的な使用法

# プロキシを起動する
proxy_start

# オプション：永続的なセッションの記録を開始する
proxy_session_start --capture_profile full --session_name "reverse-run-1"

# デバイスをプロキシを使用するように設定する（Wi-Fi設定またはインターセプター）
# デバイスにCA証明書をインストールする（proxy_get_ca_cert）

# またはインターセプターを使用してターゲットを自動設定する：
interceptor_chrome_launch                    # プロキシ付きでChromeを起動する
interceptor_spawn --command curl --args '["https://example.com"]'  # プロキシ経由のプロセスを起動する
interceptor_android_activate --serial DEVICE_SERIAL               # Androidデバイス

# 地理的位置のために上流プロキシを設定する
proxy_set_upstream --proxy_url socks5://user:pass@geo-proxy:1080

# APIレスポンスをモックする
proxy_mock_response --url_pattern "/api/v1/config" --status 200 --body '{"feature": true}'

# 認証ヘッダーを注入する（値をnullに設定するとヘッダーを削除する）
proxy_inject_headers --hostname "api.example.com" --headers '{"Authorization": "Bearer token123"}'

# キャプチャされたトラフィックを表示する
proxy_list_traffic --hostname_filter "api.example.com"
proxy_search_traffic --query "error"

# TLSフィンガープリント
proxy_list_tls_fingerprints                # 一意のJA3/JA4フィンガープリントを確認する
proxy_set_ja3_spoof --ja3 "771,4865-..."   # 送信するJA3を偽装する
proxy_set_fingerprint_spoof --preset chrome_136 --host_patterns '["example.com"]'  # 完全なフィンガープリントを偽装する
interceptor_chrome_launch --url "https://example.com"       # 偽装が有効な場合 → ステルスモードが自動的に有効になる
proxy_list_fingerprint_presets                  # 利用可能なブラウザのプリセット

# 人間らしいブラウザのインタラクション（interceptor_chrome_launchのターゲットが必要）
humanizer_move --target_id "chrome_<pid>" --x 500 --y 300
humanizer_click --target_id "chrome_<pid>" --selector "#login-button"
humanizer_type --target_id "chrome_<pid>" --text "user@example.com" --wpm 45
humanizer_scroll --target_id "chrome_<pid>" --delta_y 300
humanizer_idle --target_id "chrome_<pid>" --duration_ms 2000 --intensity subtle

# 記録されたセッションをクエリ/エクスポートする
proxy_list_sessions
proxy_query_session --session_id SESSION_ID --hostname_contains "api.example.com"
proxy_export_har --session_id SESSION_ID

📚 詳細ドキュメント

ツールリファレンス

ライフサイクル（4）

上流プロキシ（4）

インターセプトルール（7）

クイックデバッグの例：

# リクエストをシミュレートし、どのルールが勝つかを確認する
proxy_test_rule_match --mode simulate --request '{"method":"GET","url":"https://example.com/api/v1/items","headers":{"accept":"application/json"}}'

# IDで実際にキャプチャされたエクスチェンジを評価する
proxy_test_rule_match --mode exchange --exchange_id "ex_abc123"

トラフィックキャプチャ（4）

変更ショートカット（3）

TLSフィンガープリント（9）

フィンガープリントの偽装は、DockerまたはPodmanコンテナ内で実行されるcurl-impersonateを介してプロキシからリクエストを再発行することで機能します。curl-impersonateはBoringSSL + nghttp2（Chromeと同じTLSおよびHTTP/2ライブラリ）を使用するため、TLS 1.3およびHTTP/2のフィンガープリント（SETTINGS、WINDOW_UPDATE、PRIORITYフレーム）は構造的に実際のブラウザと一致します。オリジンサーバーは、プロキシの偽装されたTLS、HTTP/2、およびヘッダー順序を見る — 元のクライアントのものではありません。user_agentが設定されている場合（プリセットを介しても）、proxy-mcpはまた、ChromiumのUAクライアントヒントヘッダー（sec-ch-ua*）を正規化して、偽装されたUser-Agentに一致させます（矛盾するヒントを転送することは一般的なボットのシグナルです）。proxy_set_fingerprint_spoofをブラウザのプリセットとともに使用すると、1コマンドでセットアップできます。proxy_set_ja3_spoofは下位互換性のために残されていますが、カスタムJA3文字列は無視されます（代わりにプリセットのcurl-impersonateターゲットが使用されます）。JA4フィンガープリントはキャプチャされます（読み取り専用）が、偽装はサポートされていません。

インターセプター（18）

インターセプターは、ターゲット（ブラウザ、プロセス、デバイス、コンテナ）を自動的にプロキシ経由でトラフィックをルーティングするように設定します。

検出（3）

Chrome（4）

起動時には分離された一時プロファイルが使用され、閉じると自動的にクリーンアップされます。chrome、chromium、brave、edgeをサポートします。

フィンガープリントの偽装がアクティブな場合（proxy_set_fingerprint_spoof）、Chromeはステルスモードで起動します：chrome-launcherのデフォルトのフラグで検出可能なアーティファクトを作成するもの（例：--disable-extensionsによるchrome.runtimeの削除）は、選りすぐりの最小限のセットに置き換えられ、ページスクリプトが実行される前にCDPを介して反検出パッチが注入されます。これには、navigator.webdriver、chrome.runtimeの存在、Permissions.query、およびエラースタックのサニタイズが含まれます。

ターミナル / プロセス（2）

curl、Node.js、Python requests、Deno、Git、npm/yarnをカバーする18以上の環境変数を設定します。

Android ADB（4）

注意事項： CA証明書の注入にはルートアクセスが必要です。Android 14+（/apex/com.android.conscrypt/cacerts/）をサポートします。Wi-Fiプロキシはオプトイン（デフォルトでオフ）です。

Android Frida（3）

注意事項： デバイス上でfrida-serverが実行されている必要があります。frida-js（ホスト上にネイティブバイナリがない純粋なJS）を使用します。SSLのピン解除は、OkHttp、BoringSSL、TrustManager、システムTLSをカバーしますが、QUICまたはカスタムTLSスタックに対しては機能しない場合があります。

Docker（2）

2つのモード：exec（ライブ注入、既存のプロセスは再起動が必要）とrestart（コンテナを停止 + 再起動）。host.docker.internalをプロキシURLに使用します。

DevToolsブリッジ（14）

管理されたchrome-devtools-mcpサイドカーの周りのプロキシに安全なラッパーで、特定のinterceptor_chrome_launchターゲットにバインドされています。

注：DevToolsのレスポンスからの画像ペイロードは、大きなbase64ブロブをコンテキストに押し込まないように、MCPの出力から削除されます。 スクリーンショットにfile_pathが提供され、サイドカーが画像をインラインで返す場合、proxy-mcpはラッパー内でそれをディスクに書き込みます。

セッション（13）

長時間の実行とクラッシュ後の分析のための永続的でクエリ可能なディスク上のキャプチャ。

ヒューマナイザー — CDP入力（5）

Chrome DevToolsプロトコルを介した人間らしいブラウザ入力。現実的なタイミング、ベジェ曲線のマウスパス、および自然なキーストロークの遅延でInput.*イベントをディスパッチします。target_id（Chromeインターセプターターゲット）にバインドされます — 各ターゲットに独自の永続的なCdpSessionを管理し、DevToolsブリッジサイドカーとは独立しています。

すべてのツールは、事前のinterceptor_chrome_launchからのtarget_idを必要とします。エンジンは呼び出し間で追跡されたマウス位置を維持するため、humanizer_moveの後にhumanizer_clickを実行すると、連続したパスが生成されます。

動作の詳細：

• マウスパス：ランダムな制御点を持つ3次ベジェ曲線、フィッツの法則に基づく距離/サイズのスケーリング、オプションのオーバーシュート + 修正アーク
• タイピング：WPMからの基本遅延、バイグラム頻度（"th"などの一般的なペアはより速い）、シフトキーのペナルティ、単語境界の一時停止によって修正されます。オプションのタイポ注入は、QWERTYの近傍マップとバックスペースの修正を使用します
• スクロール：easeInOutQuadの速度曲線に従って複数のホイールイベントに分散された総デルタ
• アイドル：周期的なマイクロジャイター（±3pxの微妙な/±8pxの通常）と設定可能な強度でのランダムなマイクロスクロール

リソース

🔧 技術詳細

アーキテクチャ

• 状態：ProxyManagerシングルトンがmockttpサーバー、ルール、トラフィックを管理します
• ルールの再構築：ルールはmockttpのstart()の前に設定する必要があるため、ルールの変更は停止/再作成/再起動のサイクルをトリガーします
• トラフィックキャプチャ：on('request') + on('response')イベント、リクエストIDで関連付けられます
• リングバッファ：最大1000エントリ、ボディのプレビューは4KBに制限されます
• TLSキャプチャ：mockttpソケットメタデータからのクライアントJA3/JA4；tls.connectのモンキーパッチを介したサーバーJA3S
• TLS偽装：Docker/Podmanコンテナ内のcurl-impersonate（BoringSSL + nghttp2）；最初の偽装リクエストで遅延起動されます
• インターセプター：InterceptorManagerによって管理され、各タイプは独立して登録されます
• ヒューマナイザー：各Chromeターゲットに永続的なCdpSessionを持つシングルトンHumanizerEngine、呼び出し間でマウス位置を追跡します。純粋なTypeScript — 外部依存関係なし（ベジェパス、フィッツの法則、バイグラムタイミングはすべて内部で計算されます）

テスト

npm test              # すべてのテスト（単体 + 統合）
npm run test:unit     # 単体テストのみ
npm run test:integration  # 統合テスト
npm run test:e2e      # E2Eフィンガープリントテスト（DockerまたはPodman + Chrome + インターネットが必要）

📄 ライセンス

コアライブラリ

ベンダー化されたFridaスクリプト

src/frida-scripts/vendor/内のすべてのスクリプトは、httptoolkit/frida-interception-and-unpinning（MIT）に由来します。

• config-template.js — プロキシ/証明書の設定注入
• android-certificate-unpinning.js — TrustManager + OkHttp + BoringSSLフック
• android-system-certificate-injection.js — KeyStoreを介したランタイム証明書の注入
• android-proxy-override.js — ProxySelectorのモンキーパッチ
• native-tls-hook.js — BoringSSL/OpenSSLのネイティブフック
• native-connect-hook.js — libcのconnect()リダイレクト