proxyman-mcp-setup

Proxyman MCP 设置

配置 Agent，通过 Proxyman 自带的 stdio 桥接程序连接 Proxyman MCP。

操作规则

1. 本技能以 Shell 命令为主。MCP 工具可能尚未连接。
2. 不要使用 API 密钥或直接 HTTP MCP 配置。Proxyman MCP 使用本地 stdio 桥接可执行文件。
3. 验证成功前，必须确保 Proxyman 已安装并正在运行，且 Settings > MCP > MCP Server 已启用。
4. 保留 Agent 配置文件中现有的 MCP 服务条目。仅添加或更新 proxyman 条目。
5. 如果 Proxyman 设置中显示了确切命令，优先使用该命令。

基本原理

Proxyman MCP 包含两个本地组件：

1. AI Agent 通过 stdio 启动 Proxyman 自带的 mcp-server 可执行文件。
2. 桥接程序从 Proxyman 的应用数据文件夹读取 mcp-handshake.json。
3. 桥接程序使用握手文件中的 bearer token，将工具调用转发到正在运行的应用，地址为 http://127.0.0.1:<ephemeral-port>/mcp。
4. 桥接程序属于单个客户端会话，并会在客户端的 stdin 到达 EOF 时退出。MCP 客户端应在下一个会话中重新启动它。

不要硬编码 HTTP 端口或令牌。应用会重新生成它们。

常见的握手文件位置：

平台/构建版本	握手文件夹
macOS 原生应用	Proxyman Application Support 捆绑包文件夹，包括常规和 Setapp 捆绑包 ID
Windows Electron 应用	%APPDATA%\Proxyman
Linux Electron 应用	${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman

不要编辑握手文件。如果文件缺失或已过期，请重启 Proxyman 并重新启用 Settings > MCP。

第 1 步：确认 Proxyman 已安装

macOS

if [ -d "/Applications/Proxyman.app" ]; then
  echo "INSTALLED: /Applications/Proxyman.app"
elif mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy"' | grep -q "Proxyman.app"; then
  mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy"'
else
  echo "NOT_INSTALLED"
fi

Windows（PowerShell）

$installed = Get-ItemProperty `
  "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
  "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*",
  "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*" `
  -ErrorAction SilentlyContinue |
  Where-Object { $_.DisplayName -like "*Proxyman*" }
if ($installed) { "INSTALLED" } else { "NOT_INSTALLED" }

Linux

if command -v proxyman >/dev/null 2>&1 || ls "$HOME"/Downloads/Proxyman*.AppImage "$HOME"/Downloads/proxyman*.AppImage >/dev/null 2>&1; then
  echo "INSTALLED"
else
  echo "NOT_INSTALLED"
fi

如果未安装 Proxyman，请停止并使用 proxyman-download-setup。

第 2 步：启动 Proxyman 并启用 MCP

macOS

open -a "Proxyman"
sleep 10

Windows（PowerShell）

$candidates = @(
  "$env:LOCALAPPDATA\Programs\Proxyman\Proxyman.exe",
  "C:\Program Files\Proxyman\Proxyman.exe",
  "C:\Program Files (x86)\Proxyman\Proxyman.exe"
)
$proxymanExe = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if ($proxymanExe) { Start-Process $proxymanExe; Start-Sleep 10 }

Linux

if command -v proxyman >/dev/null 2>&1; then
  nohup proxyman >/dev/null 2>&1 &
else
  nohup "$HOME/Downloads/Proxyman.AppImage" >/dev/null 2>&1 &
fi
sleep 10

请用户打开 Proxyman Settings > MCP，并启用 “MCP Server”。如果 MCP 开关处于锁定状态，用户必须授权其 Proxyman 构建版本所要求的套餐/许可证。

如果已找到随附的 proxyman-cli，即使 Proxyman 已关闭，也可以用它保存相同的状态。请先阅读该已安装版本的 proxyman-cli mcp --help，然后仅在用户要求启用 MCP 时使用其 mcp on 操作。之后启动 Proxyman，再进行 MCP 调用。使用 proxyman-cli 技能查找可执行文件并确认准确语法；不要根据本设置指南猜测标志。

除非用户明确要求将原始标头、Cookie、查询字符串或正文发送给 Agent，否则请保持“在发送给 AI 前隐藏敏感数据”处于启用状态。

在 Linux AppImage 构建版本中，启动 Proxyman 后，应用会将打包的 MCP 桥接程序复制到稳定的配置路径，并将其标记为可执行文件。如果下方的桥接程序路径不存在，请在 Settings 中启用 MCP，重启 Proxyman，然后再次检查。

第 3 步：查找桥接可执行文件

macOS

常规构建版本：

BRIDGE_PATH="/Applications/Proxyman.app/Contents/MacOS/mcp-server"
test -x "$BRIDGE_PATH" && echo "$BRIDGE_PATH"

如果常规路径不存在，请搜索已安装的 Proxyman 应用：

mdfind 'kMDItemCFBundleIdentifier == "com.proxyman.NSProxy" || kMDItemCFBundleIdentifier == "com.proxyman.NSProxy-setapp"' |
while read -r app; do
  candidate="$app/Contents/MacOS/mcp-server"
  [ -x "$candidate" ] && echo "$candidate"
done

Windows（PowerShell）

Windows Electron 应用会将 mcp-server.exe 复制到 Proxyman.exe 所在目录。如果找不到桥接程序，请使用 Proxyman Settings > MCP 中显示的确切命令。

$exeCandidates = @(
  "$env:LOCALAPPDATA\Programs\Proxyman\Proxyman.exe",
  "C:\Program Files\Proxyman\Proxyman.exe",
  "C:\Program Files (x86)\Proxyman\Proxyman.exe"
)
$proxymanExe = $exeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1

$bridgeCandidates = @()
if ($proxymanExe) {
  $bridgeCandidates += Join-Path (Split-Path $proxymanExe -Parent) "mcp-server.exe"
}
$bridgeCandidates += @(
  "$env:LOCALAPPDATA\Programs\Proxyman\mcp-server.exe",
  "C:\Program Files\Proxyman\mcp-server.exe",
  "C:\Program Files (x86)\Proxyman\mcp-server.exe"
)

$bridge = $bridgeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if ($bridge) { $bridge } else { "NOT_FOUND: copy the path from Proxyman Settings > MCP" }

Linux

打包的 Linux AppImage 会在启动后将 mcp-server 复制到 Proxyman 的配置文件夹。优先使用该稳定副本的路径。

CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
BRIDGE_PATH="$CONFIG_HOME/Proxyman/bin/mcp-server"

if [ -x "$BRIDGE_PATH" ]; then
  echo "$BRIDGE_PATH"
else
  echo "NOT_FOUND: launch Proxyman, enable Settings > MCP, restart Proxyman, or copy the path from Settings > MCP"
fi

将 BRIDGE_PATH 设置为所选可执行文件的路径。它必须是 stdio 桥接程序，而不是 Proxyman 应用二进制文件。

第 4 步：检测 Agent 配置

依次使用环境变量、父进程和文件系统标记进行检测。

[ -n "$OPENAI_CODEX" ] && echo "codex"
[ -n "$CLAUDE_CODE_ENTRYPOINT" ] && echo "claude-code"
[ -n "$CURSOR_TRACE_ID" ] || [ "$TERM_PROGRAM" = "cursor" ] && echo "cursor"
[ -n "$VSCODE_PID" ] || [ "$TERM_PROGRAM" = "vscode" ] && echo "vscode"
[ -n "$GITHUB_COPILOT_CLI" ] && echo "copilot-cli"

备用标记：

test -d "$HOME/.codex" && echo "codex"
test -d "$HOME/.claude" && echo "claude-code"
test -d "$HOME/.cursor" && echo "cursor"
test -d ".vscode" && echo "vscode"
test -f "$HOME/.copilot/mcp-config.json" && echo "copilot-cli"
test -f "$HOME/Library/Application Support/Claude/claude_desktop_config.json" && echo "claude-desktop"

如果检测到多个 Agent，请询问用户要配置哪个 Agent。

第 5 步：添加 MCP 服务

Codex CLI

首选命令：

codex mcp add proxyman -- "$BRIDGE_PATH"

等效 TOML：

[mcp_servers.proxyman]
enabled = true
command = "BRIDGE_PATH"
args = []

配置文件：~/.codex/config.toml。

Claude Code

claude mcp add proxyman --transport stdio -- "$BRIDGE_PATH"

配置文件：~/.claude.json。

Claude Desktop

配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

服务条目：

{
  "mcpServers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {}
    }
  }
}

Cursor

配置文件：~/.cursor/mcp.json。

{
  "mcpServers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {}
    }
  }
}

VS Code / GitHub Copilot

配置文件：

• macOS：~/Library/Application Support/Code/User/mcp.json 或工作区 .vscode/mcp.json
• Linux：~/.config/Code/User/mcp.json 或工作区 .vscode/mcp.json
• Windows：%APPDATA%\Code\User\mcp.json 或工作区 .vscode\mcp.json

{
  "servers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {}
    }
  }
}

GitHub Copilot CLI

配置文件：~/.copilot/mcp-config.json。

{
  "mcpServers": {
    "proxyman": {
      "command": "BRIDGE_PATH",
      "args": [],
      "env": {},
      "tools": ["*"]
    }
  }
}

手动编辑 JSON 或 TOML 配置时，尽可能使用真正的解析器进行解析和合并。切勿替换无关的 mcpServers 或 servers 条目。

第 6 步：验证

更改配置后，重启或重新加载 Agent。

验证顺序：

1. 确认 Proxyman 正在运行。
2. 确认 Settings > MCP 显示服务正在运行。
3. 如果 Agent 支持发现功能，请让它列出 MCP 工具/资源/提示词。
4. 调用 get_version。
5. 调用 get_proxy_status。

设置成功意味着 Agent 能看到 Proxyman 工具，且 get_version 返回 Proxyman 应用/桥接响应。

工具的可用性可能因平台和构建版本而异。请以实时工具列表为准。尤其是 macOS 系统代理控制、Apple Terminal/iTerm/Ghostty 注入、.app Electron 注入以及桥接应用控制工具均面向 macOS；除非服务公开了适用的架构，否则不要在 Windows 或 Linux 上提供这些工具。

故障排除

错误	含义	操作
Proxyman is not running or MCP server not started	桥接程序无法找到 mcp-handshake.json。	启动 Proxyman 并启用 Settings > MCP。
Invalid handshake file	令牌或端口已过期。	重启 Proxyman，然后重新加载 Agent。
Cannot connect to Proxyman	应用已关闭或 MCP 服务已停止。	打开 Proxyman 并确认 MCP 状态。
Linux 桥接程序路径缺失	AppImage 尚未在配置文件夹中准备好 mcp-server。	启动 Proxyman，启用 Settings > MCP，重启 Proxyman，然后检查 ${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server。
Agent 没有 Proxyman 工具	配置路径错误或 Agent 尚未重新加载。	重新检查 BRIDGE_PATH 和配置文件，并重启 Agent。
设置完成后用户看不到流量	MCP 已连接，但尚未配置目标捕获。	使用 proxyman-https-capture，然后使用 proxyman-traffic-debugging 检查。

下一步

get_version 和 get_proxy_status 正常工作后：

• 使用 proxyman-traffic-debugging 获取完整的 MCP 操作界面；
• 使用 proxyman-https-capture 配置设备、模拟器、浏览器、运行时和框架的路由/信任；
• 使用 proxyman-debugging-tools 查看当前官方功能文档；
• 使用 proxyman-cli 执行与版本匹配的 shell 自动化操作。