shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

proxy-mcp

proxy-mcp是一个MCP服务器，提供HTTP/HTTPS中间人代理功能，支持流量捕获、实时修改、TLS指纹伪装和上游代理链，并包含多种拦截器工具用于浏览器、命令行、Docker和Android设备的自动化代理配置。

article

README

🚀 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 个）

| 工具 | 描述 | |------|-------------| | proxy_start | 启动中间人代理，自动生成 CA 证书 | | proxy_stop | 停止代理（保留流量和证书） | | proxy_status | 运行状态、端口、规则/流量计数 | | proxy_get_ca_cert | 获取 CA 证书 PEM 和 SPKI 指纹 |

上游代理工具（4 个）

| 工具 | 描述 | |------|-------------| | proxy_set_upstream | 设置全局上游代理 | | proxy_clear_upstream | 移除全局上游代理 | | proxy_set_host_upstream | 为每个主机设置上游代理覆盖 | | proxy_remove_host_upstream | 移除每个主机的上游代理覆盖 |

拦截规则工具（7 个）

| 工具 | 描述 | |------|-------------| | proxy_add_rule | 添加带有匹配器和处理程序的规则 | | proxy_update_rule | 修改现有规则 | | proxy_remove_rule | 删除规则 | | proxy_list_rules | 按优先级列出所有规则 | | proxy_test_rule_match | 测试哪些规则会匹配模拟请求或捕获的交换，并提供详细诊断信息 | | proxy_enable_rule | 启用已禁用的规则 | | proxy_disable_rule | 禁用规则但不删除 |

快速调试示例：

# 模拟一个请求，查看哪个规则会匹配
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 个）

| 工具 | 描述 | |------|-------------| | proxy_list_traffic | 带有过滤器的分页流量列表 | | proxy_get_exchange | 根据 ID 获取完整的交换详细信息 | | proxy_search_traffic | 对流量进行全文搜索 | | proxy_clear_traffic | 清除捕获缓冲区 |

修改快捷工具（3 个）

| 工具 | 描述 | |------|-------------| | proxy_inject_headers | 在匹配的流量上添加/覆盖/删除头部（将值设置为 null 可删除头部） | | proxy_rewrite_url | 重写请求 URL | | proxy_mock_response | 为匹配的请求返回模拟响应 |

TLS 指纹工具（9 个）

| 工具 | 描述 | |------|-------------| | proxy_get_tls_fingerprints | 获取单个交换的 JA3/JA4 客户端指纹和 JA3S | | proxy_list_tls_fingerprints | 列出所有流量中唯一的 JA3/JA4 指纹及其计数 | | proxy_set_ja3_spoof | 旧版：启用 JA3 欺骗（已弃用，使用 proxy_set_fingerprint_spoof） | | proxy_clear_ja3_spoof | 禁用指纹欺骗并停止 curl-impersonate 容器 | | proxy_get_tls_config | 返回当前的 TLS 配置（服务器捕获、JA3 欺骗状态） | | proxy_enable_server_tls_capture | 切换服务器端 JA3S 捕获（对 tls.connect 进行猴子补丁） | | proxy_set_fingerprint_spoof | 通过 Docker/Podman 中的 curl-impersonate 启用完整的 TLS + HTTP/2 指纹欺骗。支持浏览器预设。 | | proxy_list_fingerprint_presets | 列出可用的浏览器指纹预设（如 chrome_131、chrome_136、chrome_136_linux、firefox_133） | | proxy_check_fingerprint_runtime | 预检 Docker/Podman 是否准备好进行指纹欺骗（运行时健康状况、镜像/容器是否存在） |

指纹欺骗通过在 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 个）

| 工具 | 描述 | |------|-------------| | interceptor_list | 列出所有拦截器及其可用性和活动目标计数 | | interceptor_status | 获取特定拦截器的详细状态 | | interceptor_deactivate_all | 紧急清理：终止所有类型的活动拦截器 |

Chrome 拦截器工具（4 个）

| 工具 | 描述 | |------|-------------| | interceptor_chrome_launch | 使用代理标志和 SPKI 证书信任启动 Chrome/Chromium/Brave/Edge | | interceptor_chrome_cdp_info | 获取已启动 Chrome 的 CDP 端点（HTTP + WebSocket）和标签目标 | | interceptor_chrome_navigate | 通过已启动 Chrome 目标的 CDP 页面 WebSocket 导航标签并验证代理捕获 | | interceptor_chrome_close | 根据目标 ID 关闭 Chrome 实例 |

使用隔离的临时配置文件启动，关闭时自动清理。支持 chrome、chromium、brave、edge。 当启用指纹欺骗（proxy_set_fingerprint_spoof）时，Chrome 以隐身模式启动：chrome-launcher 的默认标志（会产生可检测的工件，如 --disable-extensions 会移除 chrome.runtime）会被替换为精心挑选的最小集合，并在任何页面脚本运行之前通过 CDP 注入反检测补丁。这涵盖了 navigator.webdriver、chrome.runtime 的存在、Permissions.query 和错误堆栈清理。

终端/进程拦截器工具（2 个）

| 工具 | 描述 | |------|-------------| | interceptor_spawn | 启动一个预先配置了代理环境变量（HTTP_PROXY、SSL 证书等）的命令 | | interceptor_kill | 终止一个已启动的进程并获取标准输出/错误输出 |

设置 18 个以上的环境变量，涵盖 curl、Node.js、Python 请求、Deno、Git、npm/yarn。

Android ADB 拦截器工具（4 个）

| 工具 | 描述 | |------|-------------| | interceptor_android_devices | 通过 ADB 列出连接的 Android 设备 | | interceptor_android_activate | 全面拦截：注入 CA 证书、ADB 反向隧道，可选 Wi-Fi 代理 | | interceptor_android_deactivate | 移除 ADB 隧道并清除 Wi-Fi 代理 | | interceptor_android_setup | 快速设置：推送 CA 证书 + ADB 反向隧道（无 Wi-Fi 代理） |

注意事项：CA 证书注入需要 root 权限。支持 Android 14+（/apex/com.android.conscrypt/cacerts/）。Wi-Fi 代理为可选（默认关闭）。

Android Frida 拦截器工具（3 个）

| 工具 | 描述 | |------|-------------| | interceptor_frida_apps | 通过 Frida 列出设备上运行的应用 | | interceptor_frida_attach | 附加到应用并注入 SSL 解锁和代理重定向脚本 | | interceptor_frida_detach | 从应用分离 Frida 会话 |

注意事项：需要在设备上运行 frida-server。使用 frida-js（纯 JS，主机上无原生二进制文件）。SSL 解锁涵盖 OkHttp、BoringSSL、TrustManager、系统 TLS，但可能对 QUIC 或自定义 TLS 堆栈无效。

Docker 拦截器工具（2 个）

| 工具 | 描述 | |------|-------------| | interceptor_docker_attach | 将代理环境变量和 CA 证书注入正在运行的容器 | | interceptor_docker_detach | 从容器中移除代理配置 |

有两种模式：exec（实时注入，现有进程需要重启）和 restart（停止并重启容器）。使用 host.docker.internal 作为代理 URL。

DevTools 桥接工具（14 个）

围绕托管的 chrome-devtools-mcp 边车的代理安全包装器，绑定到特定的 interceptor_chrome_launch 目标。 | 工具 | 描述 | |------|-------------| | interceptor_chrome_devtools_pull_sidecar | 安装/拉取 chrome-devtools-mcp，以便使用完整的 DevTools 桥接操作 | | interceptor_chrome_devtools_attach | 为一个 Chrome 拦截器目标启动绑定的 DevTools 边车会话 | | interceptor_chrome_devtools_navigate | 通过绑定的 DevTools 会话导航并验证匹配的代理流量 | | interceptor_chrome_devtools_snapshot | 从绑定的 DevTools 会话获取可访问性快照 | | interceptor_chrome_devtools_list_network | 从绑定的 DevTools 会话列出网络请求 | | interceptor_chrome_devtools_list_console | 从绑定的 DevTools 会话列出控制台消息 | | interceptor_chrome_devtools_screenshot | 从绑定的 DevTools 会话捕获屏幕截图 | | interceptor_chrome_devtools_list_cookies | 带有过滤器、分页和截断值预览的高效 cookie 列表 | | interceptor_chrome_devtools_get_cookie | 根据 cookie_id 获取一个 cookie（值会被限制以控制输出大小） | | interceptor_chrome_devtools_list_storage_keys | 带有分页和值预览的高效 localStorage/sessionStorage 键列表 | | interceptor_chrome_devtools_get_storage_value | 根据 item_id 获取一个存储值 | | interceptor_chrome_devtools_list_network_fields | 自会话创建以来从代理捕获的流量中获取高效的头部字段列表 | | interceptor_chrome_devtools_get_network_field | 根据 field_id 获取一个完整的头部字段值 | | interceptor_chrome_devtools_detach | 关闭一个绑定的 DevTools 边车会话 |

注意：为避免将大的 base64 数据块推送到上下文中，DevTools 响应中的图像有效负载会从 MCP 输出中删除。如果为截图提供了 file_path 且边车内联返回图像，proxy-mcp 会将其写入包装器中的磁盘。

会话工具（13 个）

用于长时间运行和崩溃后分析的持久、可查询的磁盘捕获。 | 工具 | 描述 | |------|-------------| | proxy_session_start | 开始持久会话捕获（预览或全正文模式） | | proxy_session_stop | 停止并完成活动的持久会话 | | proxy_session_status | 持久化的运行时状态（活动会话、字节数、磁盘容量错误） | | proxy_import_har | 将磁盘上的 HAR 文件导入新的持久会话 | | proxy_list_sessions | 列出磁盘上记录的会话 | | proxy_get_session | 获取一个会话的清单/详细信息 | | proxy_query_session | 对记录的交换进行索引查询 | | proxy_get_session_handshakes | 报告会话条目的 JA3/JA4/JA3S 握手元数据可用性 | | proxy_get_session_exchange | 从会话中获取一个交换（可选全正文） | | proxy_replay_session | 干运行或执行所选会话请求的重放 | | proxy_export_har | 将完整会话或过滤后的子集导出为 HAR 文件 | | proxy_delete_session | 删除存储的会话 | | proxy_session_recover | 在异常关闭后从记录中重建索引 |

人类行为模拟工具 — CDP 输入（5 个）

通过 Chrome DevTools 协议实现类似人类的浏览器输入。以逼真的时间、贝塞尔鼠标路径和自然的按键延迟调度 Input.* 事件。绑定到 target_id（Chrome 拦截器目标） — 为每个目标管理自己的持久 CdpSession，独立于 DevTools 桥接边车。 | 工具 | 描述 | |------|-------------| | humanizer_move | 沿着贝塞尔曲线移动鼠标，根据菲茨定律进行速度缩放和缓动时间 | | humanizer_click | 移动到元素（CSS 选择器）或坐标，然后以类似人类的时间点击。支持左/右/中键和多次点击 | | humanizer_type | 以每分钟单词数（WPM）为模型，考虑双字母频率、Shift 键惩罚、单词停顿和可选的打字错误注入，逐字符延迟输入文本 | | humanizer_scroll | 通过多个滚轮事件以 easeInOutQuad 加速度/减速度滚动 | | humanizer_idle | 通过鼠标微抖动和偶尔的微滚动模拟空闲行为，以绕过空闲检测 |

所有工具都需要之前 interceptor_chrome_launch 提供的 target_id。引擎在调用之间跟踪鼠标位置，因此 humanizer_move 之后接着 humanizer_click 会产生连续的路径。

行为细节：

  • 鼠标路径：具有随机控制点的三次贝塞尔曲线，根据菲茨定律进行距离/大小缩放，可选过冲和校正弧
  • 打字：基于 WPM 的基本延迟，受双字母频率（如常见的 "th" 更快）、Shift 键惩罚、单词边界停顿的影响。可选的打字错误注入使用 QWERTY 邻接映射和退格校正
  • 滚动：总滚动量分布在多个滚轮事件中，遵循 easeInOutQuad 速度曲线
help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端