Proxy MCP

🚀 proxy-mcp

proxy-mcp 是一個 MCP 服務器，它運行一個顯式的 HTTP/HTTPS 中間人代理（L7）。它可以捕獲請求/響應，讓你在傳輸過程中修改流量（頭部/正文/模擬/轉發/丟棄），支持上游代理鏈，並記錄與代理建立連接的 TLS 指紋（JA3/JA4），還可選擇記錄上游服務器的 JA3S。此外，它還提供了“攔截器”，可將 Chrome、命令行工具、Docker 容器以及 Android 設備/應用的流量路由到代理。

它包含 81 個工具、8 個資源和 4 個資源模板，基於 mockttp 構建。

✨ 主要特性

• 流量捕獲與修改：僅能看到配置為通過它路由的流量（並非網絡嗅探器或數據包嗅探工具），可捕獲請求和響應，並在傳輸過程中對流量進行修改，包括添加、覆蓋或刪除 HTTP 頭部，還能控制傳出頭部的順序。
• TLS 指紋處理：可以欺騙傳出的 JA3 + HTTP/2 指紋 + 頭部順序（通過 Docker/Podman 中的 curl-impersonate），但 JA4 僅用於捕獲。返回自身的 CA 證書，不暴露上游服務器證書鏈。
• 與 CDP/Playwright 協同：可與 CDP/Playwright 配合使用，二者相互補充。CDP/Playwright 用於處理瀏覽器內部操作（如 DOM、JS 執行、本地存儲、cookie 管理），而 proxy-mcp 用於捕獲和操作網絡層面的流量，還能進行流量重放。
• 多場景支持：提供多種工具和攔截器，可對瀏覽器、命令行工具、Docker 容器、Android 設備和應用的流量進行路由和管理，支持上游代理鏈，可進行 HAR 文件導入和重放，還能模擬人類操作行為以繞過機器人檢測。

📦 安裝指南

前提條件

• Node.js 22+
• Docker 或 Podman（TLS 指紋欺騙功能需要）

安裝與構建

npm install
npm run build

運行

# 標準輸入輸出傳輸（默認） —— 供 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 配置

標準輸入輸出傳輸（默認）：

{
  "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"
    }
  }
}

💻 使用示例

基礎用法

# 啟動代理
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

📚 詳細文檔

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) 命令行/進程設置

通過設置代理環境變量，將任何進程的流量路由到 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 請求、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 中間人攻擊，必須在目標環境中信任代理的 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 握手元數據。使用即時代理捕獲的流量來分析握手指紋。

工具參考

生命週期工具（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*）進行規範化，以匹配欺騙的用戶代理（轉發矛盾的提示是常見的機器人信號）。使用 proxy_set_fingerprint_spoof 和瀏覽器預設可以一鍵完成設置。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 個）

設置 18 個以上的環境變量，涵蓋 curl、Node.js、Python 請求、Deno、Git、npm/yarn。

Android ADB 攔截器工具（4 個）

注意事項：CA 證書注入需要 root 權限。支持 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 個）

有兩種模式：exec（即時注入，現有進程需要重啟）和 restart（停止並重啟容器）。使用 host.docker.internal 作為代理 URL。

DevTools 橋接工具（14 個）

圍繞託管的 chrome-devtools-mcp 邊車的代理安全包裝器，綁定到特定的 interceptor_chrome_launch 目標。

注意：為避免將大的 base64 數據塊推送到上下文中，DevTools 響應中的圖像有效負載會從 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 會產生連續的路徑。

行為細節：

• 鼠標路徑：具有隨機控制點的三次貝塞爾曲線，根據菲茨定律進行距離/大小縮放，可選過沖和校正弧
• 打字：基於 WPM 的基本延遲，受雙字母頻率（如常見的 "th" 更快）、Shift 鍵懲罰、單詞邊界停頓的影響。可選的打字錯誤注入使用 QWERTY 鄰接映射和退格校正
• 滾動：總滾動量分佈在多個滾輪事件中，遵循 easeInOutQuad 速度曲線