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 速度曲线