メインコンテンツまでスキップ

ヘッドレスモード

ウィンドウ、Dock アイコン、ダイアログなしで Proxyman を実行し、AI エージェントやスクリプトが MCP 経由で HTTPS をキャプチャ・復号できます。Proxyman 26.6.0 以降で利用できます。

ヘッドレスモードでは、Proxyman がウィンドウ、Dock やメニューバーのアイコン、ダイアログなしで動作します。Claude Code、Codex、Cursor などの AI エージェントが MCP 経由で Proxyman を起動し、HTTPS のキャプチャと復号、通信の確認、デバッグルールの作成まですべて自力で行えます。mitmproxy のように使えて、Proxyman のすべてのツールが利用できます。

備考

ヘッドレスモードは Proxyman 26.6.0 以降で利用できます。Proxyman MCP の他の機能と同様に、有料の Proxyman ライセンスが必要です。

Claude Code がヘッドレスで Proxyman を起動し、ダイアログなしで証明書を作成して、127.0.0.1:9090 経由で HTTPS を送信し、復号されたフローを読み取ります。Proxyman のウィンドウは開きません。

1. セットアップ​

コマンドの末尾に --headless を付けて、Proxyman MCP をエージェントに追加します。

Claude Code​

claude mcp add proxyman --transport stdio -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless

Codex​

codex mcp add proxyman -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server" --headless

Cursor とその他の MCP クライアント​

{
  "mcpServers": {
    "proxyman": {
      "command": "/Applications/Proxyman.app/Contents/MacOS/mcp-server",
      "args": ["--headless"]
    }
  }
}

Setapp 版では /Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server を使用してください。

以上で完了です。Proxyman を開いたり、Settings → MCP をオンにしたりする必要はありません。最初のツール呼び出しで Proxyman がヘッドレスで起動し、エージェントの作業が終わると終了します。

ヒント

--headless を付けずに Proxyman MCP を追加済みの場合は、エージェントに「Proxyman をヘッドレスモードで起動して」と頼んでください。エージェントは open_proxyman を headless: true で呼び出します。

2. ダイアログなしで HTTPS をキャプチャする​

エージェントには、たとえば次のように頼みます。

Proxyman をヘッドレスで起動し、ダイアログなしで CA を作成して、api.example.com を復号してください。そのうえで、127.0.0.1:9090 経由でテストを実行し、失敗したリクエストを表示してください。

エージェントは次の手順で作業します。

  1. Proxyman を起動する: open_proxyman を headless: true で呼び出します。プロキシのアドレスが返されます（デフォルトは http://127.0.0.1:9090）。
  2. 証明書を作成する: install_certificate を mode: generate_only で呼び出すと、Proxyman CA が作成され、信頼設定なしでログインキーチェーンに追加されるため、macOS にダイアログは表示されません。certificate_path（PEM ファイル）と spki_sha256 が返されます。
  3. ドメインを復号する: api.example.com や *.example.com のようなワイルドカードに対して enable_ssl_proxying を呼び出します。SSL Proxying をご覧ください。
  4. 通信を送信する: 各クライアントがプロキシを使用し、CA を自分で信頼します（下の表を参照）。
  5. 通信を確認する: get_flows、filter_flows、get_flow_detail が、復号されたリクエストとレスポンスを返します。
クライアントプロキシと証明書
curlcurl -x http://127.0.0.1:9090 --cacert <certificate_path> https://api.example.com
Node.js 22.21+ または 24.5+HTTPS_PROXY=http://127.0.0.1:9090 NODE_USE_ENV_PROXY=1 NODE_EXTRA_CA_CERTS=<certificate_path> node app.js
Python（requests、httpx）HTTPS_PROXY=http://127.0.0.1:9090 SSL_CERT_FILE=<certificate_path> REQUESTS_CA_BUNDLE=<certificate_path> python app.py
任意のシェルツールget_terminal_manual_command のコマンドを同じシェルで実行します。Node.js、Python、Ruby、curl 向けにプロキシと証明書が設定され、古い Node.js にも対応します。
Chrome、Playwright、Puppeteer--proxy-server=http://127.0.0.1:9090 --ignore-certificate-errors-spki-list=<spki_sha256> --user-data-dir=<temp folder>。--user-data-dir がないと、Chrome は SPKI リストを無視します。
Firefoxrun_guided_setup を firefox で実行します（先に Firefox を終了してください）。Firefox をご覧ください。
iOS シミュレータinstall_ios_simulator_certificate。iOS シミュレータ をご覧ください。

同じ手順を curl で手動実行すると次のようになります。

# 1. certificate_path from install_certificate or get_certificate_status
CA="$HOME/Library/Application Support/com.proxyman.NSProxy/app-data/proxyman-ca.pem"

# 2. Send an HTTPS request through Proxyman
curl -x http://127.0.0.1:9090 --cacert "$CA" https://httpbin.org/json

3. ヘッドレスモードでの変更点​

  • 記録は常にオンです。 Proxyman は macOS のシステムプロキシを変更しないため、127.0.0.1:9090 を指定したクライアントの通信だけがキャプチャされます。すべてのアプリの通信をキャプチャするには、エージェントに set_system_proxy を呼び出してもらうか、Network Extension を使用してください。
  • アラートやウィンドウは表示されません。 アラートになるはずの内容は、代わりに stdout に出力されます。Breakpoint もウィンドウを開かず、エージェントが list_pending_breakpoints と resolve_breakpoint で処理します。
  • すべての MCP ツールが動作します。 ただし、open_proxyman_screen や set_flow_filter など、ウィンドウの表示だけを変更する一部のツールは除きます。代わりに get_flows や filter_flows で絞り込んでください。
  • セッションファイル: open_session_file は、セッション、HAR、ログのファイルをエージェントが読み取るセッションとして開き、close_session_file はライブの通信に戻ります。
  • Access Control は確認を求めません。 プロキシポートに到達できるデバイスはすべて利用できます。この Mac からの接続だけを受け付けるには、エージェントに update_settings で proxy.listen_on_localhost_only をオンにしてもらってください。Access Control をご覧ください。
  • ウィンドウはいつでも表示できます。 Proxyman.app を開くか、open_proxyman を headless: false で呼び出します。キャプチャ済みの通信は保持されます。
  • 同時に起動できる Proxyman は 1 つです。 すでにウィンドウ付きで Proxyman が開いている場合、MCP はそれを使用し、2 つ目のヘッドレス版は起動しません。

4. 一度だけ必要な操作​

ヘッドレスモードはダイアログを表示しないため、次の手順だけは一度ご自身で行う必要があります。

  • Safari、macOS の信頼ストアを使うアプリ（URLSession）、Go: 信頼された証明書しか受け付けません。install_certificate を mode: automatic で一度実行してください。macOS がパスワードを求めます。新しい CA が作成されるため、その後で上記のクライアントごとの信頼設定を行ってください。
  • set_system_proxy: 初回のみ、Helper Tool がパスワードを求めます。
  • Network Extension: 一度だけ、macOS が許可を求めます。
  • 実機の iPhone や Android デバイス: デバイスに証明書をインストールして信頼してください。デバイスでデバッグする をご覧ください。

5. シェルまたは CI から実行する​

エージェントなしで、ヘッドレスの Proxyman を起動することもできます。

/Applications/Proxyman.app/Contents/MacOS/Proxyman --headless &

ステータスが stdout に出力され、Ctrl+C を押すか kill <pid> を実行するまで動作し続けます。操作には proxyman-cli を使います。たとえば、キャプチャした通信をエクスポートできます。

proxyman-cli export-log -m all -f har -o session.har
警告

open -a Proxyman --args --headless では起動しないでください。Proxyman がすでに起動している場合、macOS は引数を破棄してウィンドウを表示します。

詳細情報​

に最終更新