proxyman-mcp-setup

Proxyman MCP のセットアップ

Proxyman に同梱されている stdio ブリッジを通じて、エージェントが Proxyman MCP と通信できるように設定します。

運用ルール

1. このスキルはシェルを優先して使用します。MCP ツールはまだ接続されていない場合があります。
2. API キーや直接の HTTP MCP 設定は使用しないでください。Proxyman MCP は、ローカルの stdio ブリッジ実行ファイルを使用します。
3. 検証に合格するには、Proxyman がインストールされ、起動しており、「Settings > MCP > MCP Server」が有効になっている必要があります。
4. エージェントの設定ファイルにある既存の MCP サーバーエントリは保持してください。追加または更新するのは proxyman エントリだけです。
5. アプリに表示される場合は、Proxyman の「Settings > MCP」に表示されているコマンドをそのまま使用してください。

メンタルモデル

Proxyman MCP は、ローカルの 2 つの要素で構成されています。

1. AI エージェントは、Proxyman に同梱されている mcp-server 実行ファイルを stdio 経由で起動します。
2. ブリッジは、Proxyman のアプリデータフォルダーから mcp-handshake.json を読み込みます。
3. ブリッジは、ハンドシェイクファイル内のベアラートークンを使用して、実行中のアプリの http://127.0.0.1:<ephemeral-port>/mcp にツールの呼び出しを転送します。
4. ブリッジは 1 つのクライアントセッションに属し、クライアントの標準入力が 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 アクションを使用してください。MCP の呼び出しが実行可能になることを期待する前に、Proxyman を起動してください。実行ファイルの検出と正確な構文には proxyman-cli スキルを使用し、このセットアップガイドからフラグを推測しないでください。

ユーザーが明示的に、ヘッダー、Cookie、クエリー文字列、または本文を未加工のままエージェントに送信することを希望しない限り、「Redact Sensitive Data Before Sending to 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：エージェントの設定を検出する

まず環境変数を確認し、次に親プロセスを確認し、その後ファイルシステムの目印を確認します。

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

複数のエージェントが検出された場合は、どのエージェントを設定するかユーザーに尋ねてください。

ステップ 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：確認

設定を変更した後、エージェントを再起動または再読み込みします。

確認手順：

1. Proxyman が起動していることを確認します。
2. 「Settings > MCP」でサーバーが実行中であることを確認します。
3. エージェントが検出に対応している場合は、MCP ツール／リソース／プロンプトを一覧表示するよう依頼します。
4. get_version を呼び出します。
5. get_proxy_status を呼び出します。

セットアップが成功すると、エージェントから 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 を再起動してから、エージェントを再読み込みします。
Cannot connect to Proxyman	アプリが終了しているか、MCP サーバーが停止しています。	Proxyman を開き、MCP の状態を確認します。
Linux bridge path is missing	AppImage が設定フォルダーに mcp-server をまだ準備していません。	Proxyman を起動して「Settings > MCP」を有効にし、Proxyman を再起動してから、${XDG_CONFIG_HOME:-$HOME/.config}/Proxyman/bin/mcp-server を確認します。
エージェントに Proxyman のツールが表示されない	設定パスが間違っているか、エージェントが再読み込みされていません。	BRIDGE_PATH と設定ファイルを再確認し、エージェントを再起動します。
セットアップ後もユーザーにトラフィックが表示されない	MCP は接続されていますが、対象のキャプチャが設定されていません。	proxyman-https-capture を使用し、その後 proxyman-traffic-debugging で調査します。

次のステップ

get_version と get_proxy_status が動作したら、次の操作を行います。

• MCP の操作機能一式には proxyman-traffic-debugging を使用します。
• デバイス、エミュレーター、ブラウザー、ランタイム、フレームワークのルーティング／信頼設定には proxyman-https-capture を使用します。
• 最新の公式機能ドキュメントには proxyman-debugging-tools を使用します。
• バージョンに合ったシェル自動化には proxyman-cli を使用します。