proxypilot
Summary: ProxyPilot's MCP server lets an AI agent inspect and manipulate captured HTTP(S)/WebSocket traffic and configure proxy behavior.
Summarize, list, filter, search, and read recorded requests, headers, bodies, timings, and WebSocket messages.
Compare two flows with
diff_flowsto find changed query params, headers, status, bodies, and JSON paths.Add mock/map-local responses, map remote targets, and rewrite headers/query/body/JSON/status/URL.
Manage rules: list rules, remove your rules, and clear all agent-created rules.
Intercept live traffic with breakpoints: set a breakpoint, wait for a paused flow, then continue/modify/abort.
Replay recorded requests with optional URL/body/method/header/query edits, multiple sends, and concurrency.
Simulate slow networks with global or host-scoped throttle profiles or custom bandwidth/latency.
Wait for matching requests to complete and check daemon status or clear recorded sessions.
Enables capturing and inspecting HTTP(S) and WebSocket traffic from Android emulators and devices, including installing the proxy CA certificate via adb.
Enables capturing and inspecting HTTP(S) and WebSocket traffic from iOS simulators and devices, including installing the CA certificate into simulators.
Enables routing macOS apps through the proxy by toggling the system proxy, making captured app traffic available for inspection and modification.
Capture, inspect and change traffic from iOS simulators and devices, Android emulators and devices, macOS apps and Chrome. The tool is similar to Proxyman or Charles. The web UI, the CLI and the MCP server all use the same control API, so a feature added there works everywhere.
Features
Protocols: HTTP/1.1 and HTTP/2 on both sides, WebSocket with every message recorded (permessage-deflate decoded).
Traffic:
Live table with sortable columns.
Sidebar grouped by device → app → domain. iOS simulator traffic is detected from the client process.
Filters such as
host:status:method:type:.Detail panel with headers, body (JSON tree, hex), timing and GraphQL.
Rules: Map Local, Map Remote, Rewrite (headers, query, body, JSON fields, status, URL) and Breakpoints. Rules can also be added from the right-click Tools menu on any request.
Breakpoints: A paused request opens in a pop-up. You can edit it as a form, as raw HTTP or as JSON, then continue, abort or execute the edited version.
Scripts: A Rewrite step can run sandboxed JavaScript to edit headers, body, status or URL.
Record only: Limit recording to chosen hosts or apps, from Settings or the right-click menu.
Compare: Diff two requests side by side: query parameters, headers, status and JSON fields by path. Agents get the same as the
diff_flowsMCP tool.Compose and Repeat: Paste a cURL command or start from a recorded flow. Requests can be repeated N times with a set concurrency.
Setup helpers:
Install the CA into iOS simulators and Android devices (adb).
Toggle the macOS system proxy.
Capture Chrome over DevTools.
Phone certificate page with a QR code.
Network: Throttle profiles (EDGE, 3G, LTE, bad Wi-Fi, custom) per host, No caching, and opening the proxy to phones on your Wi-Fi from the toolbar.
Sessions: HAR import and export, and
.proxypilotsession files.Redaction: Tokens, cookies and passwords are masked in CLI, export and MCP output by default.
Related MCP server: mitmproxy-mcp
Quick start
Install a release (curl -fsSL https://raw.githubusercontent.com/hakanor/proxypilot/main/install.sh | sh, or brew install hakanor/tap/proxypilot), or build from source. The full walkthrough is docs/quickstart.md.
Building from source needs Go 1.26+, and Node 20+ for the web UI.
make web # build the Svelte UI into internal/api/webdist
make build # build bin/proxypilot (the UI is embedded)./bin/proxypilot ui # start the daemon if needed and open the web UIThe proxy listens on 127.0.0.1:9090. The control API and web UI are on 127.0.0.1:9091 and only accept local connections.
curl -x http://127.0.0.1:9090 http://example.com/To capture HTTPS on this Mac, trust the root certificate. This asks for your password:
./bin/proxypilot trustThen use Setup in the UI for simulators, devices and Chrome. proxypilot system-proxy on routes macOS apps through the proxy.
CLI
proxypilot list --json # captured flows, newest first
proxypilot tail # stream flows live
proxypilot show <id> --body # one flow with bodies
proxypilot wait --url '*api*' # block until a matching flow completes
proxypilot rule add breakpoint --url '*example.com*'
proxypilot curl <id> # copy a flow as cURL
proxypilot uninstall # undo system proxy and simulator CA changesEvery command is in docs/cli.md; the JSON output is described in docs/cli-json.md.
AI agents (MCP)
claude mcp add -s user proxypilot -- proxypilot mcp --agent-name claudeAgents can list and search traffic, read bodies and WebSocket messages, add rules, resolve breakpoints and throttle the network. Setup: docs/mcp.md. How an agent should use it, with scenarios to copy into your project: docs/AGENTS.md.
Development
Path | What |
| CLI entry point |
| MITM proxy, TLS, HTTP/1.1, WebSocket |
| Recorder and SQLite store |
| Rules engine and paused flows |
| Control API (REST + WebSocket) and the embedded UI |
| MCP server |
| App icon (source of truth) |
| Svelte 5 + Tailwind v4 + shadcn-svelte UI |
| App icon PNGs and the GitHub social preview |
Commands:
make testruns the Go tests.cd web && npm run checktype-checks the UI.cd web && npm run devruns the UI with hot reload against a running daemon. SetPROXYPILOT_TOKENfirst; seeweb/vite.config.ts.make iconsre-exports the icon after you editinternal/brand/icon.svg.Tests that launch a real Chrome only run with
PROXYPILOT_CHROME_TEST=1.
Docs:
Users: quickstart, devices and troubleshooting, CLI reference (
make docsregenerates it), security.Releases:
.goreleaser.yamlandinstall.sh.
Available Tools
20 toolsadd_map_localCDestructive
Mock responses: matching requests get this content instead of (or, with mode=body_only, on top of) the server's answer. Expires after ttl (default 1h).
Inputs: url (required), ttl, body, file, +7 more.
add_map_remoteADestructive
Send matching requests to another server, e.g. prod → staging or a local dev server. A trailing * on to keeps the rest of the original path.
Inputs: to (required), url (required), ttl, name, +1 more.
add_rewriteADestructive
Edit matching traffic in flight. Steps run in order. Types: set_header/add_header {name,value}, remove_header {name}, set_query {name,value} / remove_query {name} (request), replace_body {pattern,value,regex}, json_set {path:"$.user.isPremium", value:"true"} (value is JSON text), json_remove {path}, set_status {status} (response), set_url {value} / set_path {value} (request). Compressed bodies are decoded first.
Inputs: url (required), steps (required), ttl, name, +2 more.
clear_agent_rulesADestructive
Delete every rule you created. Do this when you are done mocking or intercepting.
Inputs: no named parameters.
clear_sessionADestructive
Delete all recorded traffic (the user's too). Only do this when the user asked for a clean slate.
Inputs: no named parameters.
diff_flowsARead-onlyDestructive
What changed from request a to request b: method, host, path, each query parameter, headers, status, and bodies (JSON by path like $.items[0].price, text by line). Use it to compare a working request with a failing one, or before and after an app change. Only differences are returned; secrets stay masked.
Inputs: a (required), b (required).
get_requestARead-onlyDestructive
One request: timing, headers and a decoded body excerpt. Use path to pick part of a JSON body, offset to read on.
Inputs: id (required), body, path, offset, +2 more.
get_statusBRead-onlyDestructive
Daemon state: proxy address, flow count, active rules, paused breakpoints, whether recording.
Inputs: no named parameters.
get_websocket_messagesBRead-onlyDestructive
Messages of a WebSocket (status 101) request, oldest first. dir up = app → server, down = server → app. Page with after = previous next.
Inputs: id (required), after, limit, max_text.
list_requestsCRead-onlyDestructive
Recent requests, newest first, one text line each (see format). Filter rather than paging.
Inputs: host, type, group, limit, +6 more.
list_rulesBRead-onlyDestructive
All rules in evaluation order. You may only change rules whose owner is you (see get_status).
Inputs: no named parameters.
remove_ruleCDestructive
Delete one of your rules.
Inputs: id (required).
repeat_requestADestructive
Send a recorded request again, optionally edited (rules apply unless bypass_rules). Returns the new ids with status and time.
Inputs: id (required), url, body, count, +6 more.
resume_breakpointADestructive
Continue, edit (modify) or abort a flow paused by your breakpoint. Edits apply to the paused phase (request or response).
Inputs: id (required), action (required), url, body, +4 more.
search_trafficARead-onlyDestructive
Find requests whose URL, headers or body contain some text.
Inputs: query (required), in, limit.
set_breakpointADestructive
Pause matching requests (before the server) or responses (before the app); then wait_for_breakpoint and resume_breakpoint. Unanswered flows continue after timeout.
Inputs: url (required), ttl, name, phase, +3 more.
set_throttleADestructive
Simulate a slow network (latency, then limited bandwidth) to reproduce timeouts and slow-loading bugs. Affects everyone using the proxy: set enabled=false when done.
Inputs: enabled (required), hosts, profile, up_kbps, +2 more.
summarize_trafficARead-onlyDestructive
Start here. Totals, status groups, failing endpoints grouped (with the last flow id of each) and the slowest request for a time window.
Inputs: since.
wait_for_breakpointARead-onlyDestructive
Block until one of your breakpoints pauses a flow, then return it for resume_breakpoint.
Inputs: timeout_seconds (required), url, phase.
wait_for_requestARead-onlyDestructive
Block until a request whose URL matches completes, then return it. Start this, then trigger the action in the app.
Inputs: url (required), timeout_seconds (required), method, status, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools target clearly distinct facets (viewing: list/get/search/diff/summarize; rules: add_map_local/add_map_remote/add_rewrite; breakpoints: set/wait/resume). The only mild overlap is within the rule-creation family, where a user must read descriptions to distinguish mocking from remote redirect from in-flight rewrite, but the distinctions are spelled out.
All names are consistently snake_case verb_noun (list_requests, get_request, add_rewrite, set_throttle, wait_for_breakpoint, clear_session). Minor variation like add_map_local vs add_rewrite reflects resource subtypes but stays within the same predictable pattern.
20 tools is on the heavier side, but the domain genuinely spans traffic recording, viewing, rule manipulation, breakpoints, throttling, and replay, so each tool earns its place. It sits slightly above the ideal range but is defensible for the scope.
Full lifecycle coverage: capture (list/get/search/diff/summarize), mutate (mock/redirect/rewrite/breakpoint/throttle), replay (repeat_request), and cleanup (clear_agent_rules/clear_session). Only trivial gap is no direct edit of an existing rule, which is workable via delete+re-add.
Maintenance
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
AI-native mock API server with MCP. Create REST/SOAP mocks from Claude, Cursor, or Windsurf.
Free MCP debugging tools for AI agents and developers. Diagnose failed API and MCP tool calls, identify HTTP errors, validate tool arguments against supported JSON Schema rules, and get actionable troubleshooting recommendations.
Capture, inspect & debug HTTPS traffic across iOS, Android, browsers & backends — 304 MCP tools.
Related MCP Servers
- AlicenseBqualityCmaintenanceIntegrates Charles Proxy with MCP clients to provide real-time and historical network traffic capture and structured analysis. It features a summary-first approach that filters noise and desensitizes data for efficient, low-token agent debugging and monitoring.18112 PyPI333MIT
- FlicenseBqualityDmaintenanceA lightweight MCP server built on mitmproxy that lets LLMs capture, inspect, replay, and modify HTTP traffic through a set of focused tools.138-
- FlicenseAqualityDmaintenanceAn MCP server that gives AI agents the power to record, replay, and mock mobile app interactions — combining Maestro UI automation with Proxyman network capture to generate complete, self-contained test scripts.331-
- AlicenseNot gradedqualityBmaintenanceAn MCP server that enables AI agents to intercept, inspect, and modify HTTP traffic, with tools for searching, filtering, and managing captured requests and interceptors.8MIT