proxyman-mcp-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Proxyman MCP Setup

Proxyman MCP 设置

Configure an agent to talk to Proxyman MCP through Proxyman's bundled stdio bridge.

通过Proxyman自带的stdio桥接程序，配置代理与Proxyman MCP通信。

Operating Rules

操作规则

This skill is shell-first. MCP tools may not be connected yet.
Do not use API-key or direct HTTP MCP configuration. Proxyman MCP uses a local stdio bridge executable.
Proxyman must be installed, running, and have Settings > MCP > MCP Server enabled before verification can pass.
Preserve existing MCP server entries in agent config files. Add or update only the
```
proxyman
```
entry.
Prefer the exact command shown in Proxyman Settings > MCP when the app exposes one.

本技能优先使用Shell命令操作。此时MCP工具可能尚未连接。
请勿使用API密钥或直接HTTP MCP配置。Proxyman MCP使用本地stdio桥接可执行文件。
在验证通过前，必须确保Proxyman已安装、运行，且已开启「设置 > MCP > MCP服务器」。
保留代理配置文件中已有的MCP服务器条目，仅添加或更新
```
proxyman
```
条目。
如果应用显示相关命令，优先使用Proxyman设置 > MCP中展示的精确命令。

Mental Model

核心原理

Proxyman MCP has two local pieces:

The AI agent launches Proxyman's bundled
```
mcp-server
```
executable over stdio.
The bridge reads
```
mcp-handshake.json
```
from Proxyman's app data folder.
The bridge forwards tool calls to the running app at
```
http://127.0.0.1:<ephemeral-port>/mcp
```
with a bearer token from the handshake file.

Do not hardcode the HTTP port or token. The app regenerates them.

Common handshake locations:

Platform/build	Handshake folder
macOS native app	Proxyman Application Support bundle folder, including regular and Setapp bundle IDs
Windows Electron app	`%APPDATA%\Proxyman`
Linux Electron app	`${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman`

Do not edit the handshake file. If it is missing or stale, restart Proxyman and re-enable Settings > MCP.

Proxyman MCP包含两个本地组件：

AI代理通过stdio启动Proxyman自带的
```
mcp-server
```
可执行文件。
桥接程序从Proxyman的应用数据文件夹读取
```
mcp-handshake.json
```
文件。
桥接程序将工具调用转发至运行中的应用，地址为
```
http://127.0.0.1:<临时端口>/mcp
```
，使用握手文件中的Bearer令牌。

请勿硬编码HTTP端口或令牌，应用会自动重新生成这些信息。

常见握手文件位置：

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

请勿编辑握手文件。如果文件缺失或失效，重启Proxyman并重新开启「设置 > MCP」。

Step 1: Verify Proxyman Is Installed

步骤1：验证Proxyman已安装

macOS

bash

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

bash

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)

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

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

bash

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

If Proxyman is not installed, stop and use

proxyman-download-setup

bash

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

。

Step 2: Launch Proxyman And Enable MCP

步骤2：启动Proxyman并启用MCP

macOS

bash

open -a "Proxyman"
sleep 10

bash

open -a "Proxyman"
sleep 10

Windows (PowerShell)

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 }

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

bash

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

Ask the user to open Proxyman Settings > MCP and enable "MCP Server". If the MCP toggle is locked, the user must authorize the plan/license required by their Proxyman build.

Keep "Redact Sensitive Data Before Sending to AI" enabled unless the user explicitly wants raw headers, cookies, query strings, or bodies sent to the agent.

On Linux AppImage builds, launching Proxyman lets the app copy the packaged MCP bridge into a stable config path and mark it executable. If the bridge path below is missing, enable MCP in Settings, restart Proxyman, and check again.

bash

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设置 > MCP并启用「MCP服务器」。如果MCP开关被锁定，用户需要为其Proxyman版本授权对应的套餐/许可证。

保持「发送至AI前编辑敏感数据」开启，除非用户明确要求将原始请求头、Cookie、查询字符串或请求体发送给代理。

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

Step 3: Resolve The Bridge Executable

步骤3：定位桥接可执行文件

macOS

Regular build:

bash

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

If the regular path is missing, search installed Proxyman apps:

bash

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

常规版本：

bash

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

如果常规路径缺失，搜索已安装的Proxyman应用：

bash

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)

The Windows Electron app copies

mcp-server.exe

beside

Proxyman.exe

. If no bridge is found, use the exact command from Proxyman Settings > MCP.

powershell

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

Windows Electron应用会将

mcp-server.exe

复制到

Proxyman.exe

所在目录。如果未找到桥接程序，请使用Proxyman设置 > MCP中显示的精确命令。

powershell

$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

The packaged Linux AppImage copies

mcp-server

into Proxyman's config folder after launch. Prefer that stable copied path.

bash

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

Set

BRIDGE_PATH

to the chosen executable path. It must be the stdio bridge, not the Proxyman app binary.

打包的Linux AppImage版本启动后会将

mcp-server

复制到Proxyman的配置文件夹，优先使用这个稳定的复制路径。

bash

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应用二进制文件。

Step 4: Detect The Agent Config

步骤4：检测代理配置

Use environment variables first, then parent process, then filesystem markers.

bash

[ -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"

Fallback markers:

bash

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"

If multiple agents are detected, ask the user which agent they want to configure.

优先使用环境变量，然后是父进程，最后是文件系统标记。

bash

[ -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"

备用标记：

bash

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"

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

Step 5: Add The MCP Server

步骤5：添加MCP服务器

Codex CLI

Preferred command:

bash

codex mcp add proxyman -- "$BRIDGE_PATH"

Equivalent TOML:

toml

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

Config file:

~/.codex/config.toml

推荐命令：

bash

codex mcp add proxyman -- "$BRIDGE_PATH"

等效TOML配置：

toml

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

配置文件：

~/.codex/config.toml

。

Claude Code

bash

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

Config file:

~/.claude.json

bash

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

配置文件：

~/.claude.json

。

Claude Desktop

Config file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Server entry:

json

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

配置文件：

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

服务器条目：

json

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

Cursor

Config file:

~/.cursor/mcp.json

json

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

配置文件：

~/.cursor/mcp.json

。

json

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

VS Code / GitHub Copilot

Config file:

macOS:

~/Library/Application Support/Code/User/mcp.json

or workspace

.vscode/mcp.json

Linux:

~/.config/Code/User/mcp.json

or workspace

.vscode/mcp.json

Windows:

%APPDATA%\Code\User\mcp.json

or workspace

.vscode\mcp.json

json

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

配置文件：

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

json

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

GitHub Copilot CLI

Config file:

~/.copilot/mcp-config.json

json

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

When editing JSON or TOML config manually, parse and merge with a real parser when possible. Never replace unrelated

mcpServers

servers

entries.

配置文件：

~/.copilot/mcp-config.json

。

json

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

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

mcpServers

或

servers

条目。

Step 6: Verify

步骤6：验证

Restart or reload the agent after changing config.

Verification sequence:

Confirm Proxyman is running.
Confirm Settings > MCP shows the server running.
Ask the agent to list MCP tools/resources/prompts if it supports discovery.
Call
```
get_version
```
.
Call
```
get_proxy_status
```
.

Successful setup means the agent can see Proxyman tools and

get_version

returns a Proxyman app/bridge response.

Tool availability can vary by platform and build. Treat the live tool list as authoritative. In particular, macOS system proxy control, Apple Terminal/iTerm/Ghostty injection,

.app

Electron injection, and bridge app-control tools are macOS-oriented; do not offer them on Windows or Linux unless that server exposes an applicable schema.

修改配置后重启或重新加载代理。

验证流程：

确认Proxyman正在运行。
确认设置 > MCP显示服务器正在运行。
如果代理支持发现功能，请让其列出MCP工具/资源/提示词。
调用
```
get_version
```
。
调用
```
get_proxy_status
```
。

设置成功意味着代理可以识别Proxyman工具，且

get_version

返回Proxyman应用/桥接程序的响应。

工具可用性因平台和版本而异，请以实时工具列表为准。特别注意，macOS系统代理控制、Apple Terminal/iTerm/Ghostty注入、

.app

Electron注入和桥接程序应用控制工具均为macOS专属；除非服务器暴露了适用的架构，否则请勿在Windows或Linux平台提供这些工具。

Troubleshooting

故障排查

Error	Meaning	Action
`Proxyman is not running or MCP server not started`	Bridge cannot find `mcp-handshake.json` .	Launch Proxyman and enable Settings > MCP.
`Invalid handshake file`	Token or port is stale.	Restart Proxyman, then reload the agent.
`Cannot connect to Proxyman`	App is closed or MCP server stopped.	Open Proxyman and confirm MCP status.
Linux bridge path is missing	The AppImage has not prepared `mcp-server` in the config folder yet.	Launch Proxyman, enable Settings > MCP, restart Proxyman, then check `${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server` .
Agent has no Proxyman tools	Config path is wrong or agent was not reloaded.	Re-check `BRIDGE_PATH` , config file, and restart the agent.
User sees no traffic after setup	MCP is connected but capture is not configured.	Use `proxyman-traffic-debugging` and start with `get_proxy_status` .

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

Next Step

下一步

Once

get_version

and

get_proxy_status

work, use

proxyman-traffic-debugging

for traffic inspection, setup diagnosis, rule creation, Compose, WebSocket debugging, certificates, and Proxyman MCP operations.

当

get_version

和

get_proxy_status

正常工作后，可使用

proxyman-traffic-debugging

进行流量检查、设置诊断、规则创建、Compose、WebSocket调试、证书管理和Proxyman MCP操作。