proxy-mcp
proxy-mcp is an MCP server that runs an HTTP/HTTPS MITM proxy with traffic interception, TLS fingerprinting/spoofing, browser/process/Docker/Android interception, and Playwright-driven stealth browser automation.
Start/stop an explicit HTTP/HTTPS MITM proxy with auto-generated CA cert and inspect status/cert
Capture, list, search, and clear HTTP traffic with filters and per-exchange details
Add/update/remove interception rules: passthrough, mock, forward, drop, header injection, URL rewrite, request/response transforms
Chain global or per-host upstream proxies (SOCKS4/5, HTTP, HTTPS, PAC) with redacted credentials
Capture TLS fingerprints (JA3/JA4/JA3S) and spoof outgoing TLS+HTTP/2 fingerprints via browser presets
Launch stealth Chromium (cloakbrowser) or camoufox and drive it with navigation, snapshots, screenshots, JS evaluation, cookies/storage/network inspection
Spawn CLI/processes and attach Docker containers with proxy env vars and CA trust automatically
Intercept Android devices via ADB and Frida (cert injection, tunnels, SSL unpinning)
Record persistent sessions, import/export HAR, query/search bodies, and replay requests
Perform human-like mouse, click, type, scroll, and idle behavior on browser targets
Set up mobile/transparent proxy capture with iptables scripts for rogue-AP style interception
Provides comprehensive traffic interception for Android devices, including CA certificate injection via ADB, reverse tunneling, and SSL unpinning using Frida scripts.
Enables automated launching of the Brave browser with integrated proxy configuration for capturing and modifying web traffic.
Automates proxy configuration for curl commands by setting environment variables to route traffic through the MITM proxy for inspection.
Supports intercepting Deno network traffic by automatically configuring proxy environment variables for spawned processes.
Injects proxy settings and CA certificates into running Docker containers to capture and inspect containerized network traffic.
Enables monitoring and manipulation of Git network requests by automatically configuring proxy environment variables.
Allows for the interception of Node.js network traffic by configuring proxy environment variables and SSL certificate trust for spawned processes.
Routes npm network activity through the proxy by setting appropriate environment variables to capture and inspect package management traffic.
Enables interception of Python application traffic, including support for the requests library, through automated environment variable injection.
Routes yarn network activity through the proxy by setting appropriate environment variables to capture and inspect package management traffic.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@proxy-mcp intercept traffic to api.example.com and show the headers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
proxy-mcp
proxy-mcp is an MCP server that runs an explicit HTTP/HTTPS MITM proxy (L7). It captures requests/responses, lets you modify traffic in-flight (headers/bodies/mock/forward/drop), supports upstream proxy chaining, and records TLS fingerprints for connections to the proxy (JA3/JA4) plus optional upstream server JA3S. Ships "interceptors" to route the cloakbrowser stealth browser, CLI tools, and Docker containers through the proxy, plus Playwright-driven browser automation with locator-based click, typing, scroll, and ARIA snapshots.
72 tools + 7 resources + 3 resource templates. Built on mockttp and cloakbrowser.
proxy-mcp is no longer published to npmjs. npm's publishing system has become too annoying to be worth it — expiring tokens that silently break releases, and a mandatory passkey/2FA enrollment maze just to change a package setting. Distribution now happens directly from this repository:
npx -y "github:yfe404/proxy-mcp#semver:^3"Versions ≤ 3.3.2 remain on npmjs but will never be updated —
npx -y proxy-mcp@latest silently stays stale. Update your MCP config to the
GitHub form above. See Setup.
Table of Contents
Related MCP server: httptoolkit-mcp
Setup
Quick install (Claude Code)
claude mcp add proxy-mcp -- npx -y "github:yfe404/proxy-mcp#semver:^3"This installs proxy-mcp as an MCP server using stdio transport, straight from
GitHub — no registry involved. The #semver:^3 range resolves against this
repo's version tags, so new releases are picked up automatically.
Note: the first install compiles from source (a
preparebuild), so it takes a few seconds longer than a registry tarball — subsequent launches use the npx cache. Why not npmjs anymore? See the announcement at the top: their publishing system got too annoying.
Scopes:
# Per-user (available in all projects)
claude mcp add --scope user proxy-mcp -- npx -y "github:yfe404/proxy-mcp#semver:^3"
# Per-project (shared via .mcp.json, commit to repo)
claude mcp add --scope project proxy-mcp -- npx -y "github:yfe404/proxy-mcp#semver:^3"To pin an exact release instead, use github:yfe404/proxy-mcp#v3.4.0.
Prerequisites
Node.js 20+
From source (development)
git clone https://github.com/yfe404/proxy-mcp.git
cd proxy-mcp
npm install
npm run build# stdio transport (default) — used by MCP clients like Claude Code
node dist/index.js
# Streamable HTTP transport — exposes /mcp endpoint for scripting
node dist/index.js --transport http --port 3001--transport and --port also accept env vars TRANSPORT and PORT.
PROXY_MCP_DEBUG=1 adds debug lines to stderr, one per request the client
cancels: request aborted by client: <method> <url>.
PROXY_MCP_UPSTREAM_PASSWORD and PROXY_MCP_UPSTREAM_HOST keep an upstream
proxy password out of the transcript — see
Keeping the upstream password out of the transcript.
Manual MCP configuration
The configured server alias controls Claude's generated tool prefix. The examples below use proxy-mcp, so Claude Code exposes tools as mcp__proxy-mcp__<tool_name>. If you rename the server key to proxy, use mcp__proxy__<tool_name> instead.
Claude Code CLI:
# stdio (default)
claude mcp add proxy-mcp -- npx -y "github:yfe404/proxy-mcp#semver:^3"
# From local clone
claude mcp add proxy-mcp -- node /path/to/proxy-mcp/dist/index.js
# HTTP transport for scripting
claude mcp add --transport http proxy-mcp http://127.0.0.1:3001/mcp.mcp.json (project-level, commit to repo):
{
"mcpServers": {
"proxy-mcp": {
"command": "npx",
"args": ["-y", "github:yfe404/proxy-mcp#semver:^3"]
}
}
}Streamable HTTP transport:
{
"mcpServers": {
"proxy-mcp": {
"type": "streamable-http",
"url": "http://127.0.0.1:3001/mcp"
}
}
}HTTP Proxy Configuration
1) Start proxy and get endpoint
proxy_startUse the returned port and endpoint http://127.0.0.1:<port>.
2) Browser setup (recommended: interceptor)
Use the browser interceptor so proxy flags and cert trust are configured automatically. Launches cloakbrowser — a stealth-patched Chromium with source-level C++ fingerprint patches and humanize mode on by default:
interceptor_browser_launch --url "https://example.com"Drive the page with Playwright-backed tools (no CDP, no sidecar — target_id is all you need):
interceptor_browser_navigate --target_id "browser_<id>" --url "https://apify.com"
interceptor_browser_snapshot --target_id "browser_<id>"
interceptor_browser_screenshot --target_id "browser_<id>" --file_path "/tmp/shot.png"3) Browser setup (manual fallback)
If launching a browser manually, pass the proxy flag yourself:
google-chrome --proxy-server="http://127.0.0.1:<port>"4) CLI/process setup
Route any process through proxy-mcp by setting proxy env vars:
export HTTP_PROXY="http://127.0.0.1:<port>"
export HTTPS_PROXY="http://127.0.0.1:<port>"
export NO_PROXY="localhost,127.0.0.1"If the client verifies TLS, trust the proxy-mcp CA certificate (see proxy_get_ca_cert) or use the Terminal interceptor (interceptor_spawn) which sets proxy env vars plus common CA env vars (curl, Node, Python requests, Git, npm/yarn, etc.):
interceptor_spawn --command curl --args '["-s","https://example.com"]'Explicit curl examples:
curl --proxy http://127.0.0.1:<port> http://example.com
curl --proxy http://127.0.0.1:<port> https://example.com5) Upstream proxy chaining
Set optional proxy chaining from proxy-mcp to another upstream proxy (for geolocation, auth, or IP reputation):
Client/app → proxy-mcp (local explicit proxy) → upstream proxy (optional chaining layer)proxy_set_upstream --proxy_url "socks5://user:pass@upstream.example:1080"Supported upstream URL schemes: socks4://, socks5://, http://, https://, pac+http://.
Keeping the upstream password out of the transcript
Tool calls and tool results are both persisted by the MCP client. To avoid writing an upstream password there on every call, set it in the server's environment and pass a URL with a username but no password.
Two variables are required, and both have to be in the environment of the server process, which the MCP client spawns. Exporting them in the shell you launch the client from may reach it — CLI clients pass their own environment through — but that depends on the client and is lost the moment the server is started any other way. Put them in the client's server config:
variable | meaning |
| the password to fill in |
| the only hostname it may be sent to — a bare hostname, no scheme, port or path |
claude mcp add proxy-mcp \
-e PROXY_MCP_UPSTREAM_PASSWORD=s3cret \
-e PROXY_MCP_UPSTREAM_HOST=upstream.example \
-- npx -y "github:yfe404/proxy-mcp#semver:^3"{
"mcpServers": {
"proxy-mcp": {
"command": "npx",
"args": ["-y", "github:yfe404/proxy-mcp#semver:^3"],
"env": {
"PROXY_MCP_UPSTREAM_PASSWORD": "s3cret",
"PROXY_MCP_UPSTREAM_HOST": "upstream.example"
}
}
}
}Then omit the password from the call:
proxy_set_upstream --proxy_url "http://user@upstream.example:1080"
# routes as http://user:s3cret@upstream.example:1080Why the host variable exists. Without it, a caller who cannot read the
password could still name any host and have the password delivered there — the
proxy sends it on the first request, and the transcript would show only ***.
The hostname is matched case-insensitively and exactly, with no wildcards; the
port is not part of the match, so one variable covers a provider offering
several. A URL naming any other host is left alone. If
PROXY_MCP_UPSTREAM_PASSWORD is set and PROXY_MCP_UPSTREAM_HOST is not,
nothing is merged at all: a half-configuration fails closed rather than
becoming an unbound credential.
This keeps the password out of tool arguments and responses, not out of reach.
interceptor_spawnruns an arbitrary command as the server user, so a caller can read the client config file the password is configured in — and on Linux/proc/<pid>/environ. The variable removes the routine exposure of writing a credential into every tool call; it is not a sandbox, and anyone who can callinterceptor_spawnshould be treated as able to obtain the password.
The response reports which credential was used — passwordSource is env,
url or none. none means no password was applied to a URL that names a
user: either the credential is genuinely username-only, or the server does not
have both variables set for this host. The field is omitted for a URL with no
username, where the question does not arise.
Applies to proxy_set_upstream and proxy_set_host_upstream. A URL that
already carries a password is used as-is, so existing calls are unaffected. One
credential covers all upstreams at the pinned host; a URL without a username is
left alone.
Username-only credentials at the pinned host cannot be expressed. A URL with a username and no password is exactly the syntax that requests the merge, and
user:@hostcannot signal otherwise — the URL parser erases the empty password before the server sees it. If the pinned host authenticates on the username alone, unsetPROXY_MCP_UPSTREAM_PASSWORDfor that server.
socks*://upstreams: no:in the password. socks-proxy-agent splits the credential on the first:and keeps only what follows, sopa:sswould authenticate aspa. Rather than deliver half a password silently, a socks upstream is refused with an error whenPROXY_MCP_UPSTREAM_PASSWORDcontains:. The truncation itself is a toolchain limitation, not something this introduces — a literalsocks5://user:pa%3Ass@host:1080truncates the same way, and nothing can guard that.http://,https://andpac+http://upstreams take the whole password.
A
:in the username is refused on every scheme. Basic auth splits the decoded pair at the first colon (RFC 7617), and socks-proxy-agent does the same, so a username ofgro:upswith passwords3cretreaches the proxy as usergro, passwordups:s3cret— the merged password silently discarded. No scheme can carry it, so the merge refuses rather than guess. Put the whole credential inproxy_urlinstead.
Responses redact credentials — the password in userinfo, with path segments
masked and the query and fragment dropped, since a pac+http:// token may live
in any of those:
Global upstream set to http://user:***@upstream.example:1080/
Global upstream set to pac+http://pac.example.com/***proxy_status and the proxy://status resource are redacted the same way. A
PAC URL's filename is masked along with the rest of the path, so a confirmation
message shows the host and nothing else.
The username is not redacted. For several providers it is configuration rather than a secret — Apify Proxy encodes proxy group, country and sticky-session id there — and showing it is what makes the confirmation useful. If your provider puts a secret in the username field, do not rely on these messages being safe to share.
Typical geo-routing examples:
# Route ALL outgoing traffic from proxy-mcp via a geo proxy
proxy_set_upstream --proxy_url "socks5://user:pass@fr-exit.example.net:1080"
# Bypass upstream for local/internal hosts
proxy_set_upstream --proxy_url "http://user:pass@proxy.example.net:8080" --no_proxy '["localhost","127.0.0.1",".corp.local"]'
# Route only one hostname via a dedicated upstream (overrides global)
proxy_set_host_upstream --hostname "api.example.com" --proxy_url "https://user:pass@us-exit.example.net:443"
# Remove overrides when done
proxy_remove_host_upstream --hostname "api.example.com"
proxy_clear_upstreamFor HTTPS MITM, the proxy CA must be trusted in the target environment (proxy_get_ca_cert).
6) Validate and troubleshoot quickly
proxy_list_traffic --limit 20
proxy_search_traffic --query "example.com"Common issues:
Traffic from the wrong browser instance (fix: always pass
target_idfrominterceptor_browser_launch)HTTPS cert trust missing on target
NO_PROXYbypassing expected hostsFirst launch is slow: cloakbrowser downloads a ~200 MB stealth Chromium binary on first use (cached afterwards)
7) HAR import + replay
Import HAR into a persisted session, then analyze with existing session query/findings tools:
proxy_import_har --har_file "/path/to/capture.har" --session_name "imported-run"
proxy_list_sessions
proxy_query_session --session_id SESSION_ID --hostname_contains "api.example.com"
proxy_get_session_handshakes --session_id SESSION_IDReplay defaults to dry-run (preview only). Execute requires explicit mode:
# Preview what would be replayed
proxy_replay_session --session_id SESSION_ID --mode dry_run --limit 20
# Execute replay against original hosts
proxy_replay_session --session_id SESSION_ID --mode execute --limit 20
# Optional: override target host/base URL while preserving path+query
proxy_replay_session --session_id SESSION_ID --mode execute --target_base_url "http://127.0.0.1:8081"Note: imported HAR entries (and entries created by proxy_replay_session) do not carry JA3/JA4/JA3S handshake metadata. Use live proxy-captured traffic to analyze handshake fingerprints.
Boundaries
Only sees traffic configured to route through it (not a network tap or packet sniffer)
Spoofs outgoing JA3 + HTTP/2 fingerprint + header order (via impit — native Rust TLS impersonation), not JA4 (JA4 is capture-only)
Can add, overwrite, or delete HTTP headers; outgoing header order can be controlled via fingerprint spoofing
Returns its own CA certificate — does not expose upstream server certificate chains
TLS ClientHello Passthrough (browser via interceptor)
When cloakbrowser is launched via interceptor_browser_launch, proxy-mcp forwards the browser's original TLS ClientHello to the upstream server for document loads and same-origin sub-resource requests. The target server sees an authentic Chrome TLS fingerprint — not the proxy's.
This is a key difference from typical MITM proxies (mitmproxy, Charles, Fiddler) which re-terminate TLS with their own fingerprint, making MITM trivially detectable by anti-bot systems via JA3/JA4 analysis.
How to verify passthrough is working:
proxy_list_tls_fingerprints --hostname_filter "example.com"JA3 varies across requests to the same host — this is expected; Chrome randomizes cipher suite order per-connection (feature since Chrome 110+)
JA4 stays stable — same cipher/extension set, just different ordering
JA3 variation + JA4 stability = authentic Chrome TLS passthrough confirmed
When passthrough applies vs. when spoofing is needed:
Traffic source | TLS behavior | Action needed |
cloakbrowser via | Browser's native ClientHello forwarded (passthrough) | None — fingerprint is authentic |
cloakbrowser via | Re-issued via impit with spoofed TLS |
|
Non-browser clients (curl, Python, | Proxy's own TLS |
|
HAR replay ( | Proxy's own TLS |
|
Built on stealth browsers + Playwright
Browser automation uses cloakbrowser for stealth-patched Chromium, driven through Playwright. There is no CDP sidecar or hand-rolled stealth script in proxy-mcp. Downstream tools take a browser_* target from interceptor_browser_launch.
Capability | proxy-mcp |
See/modify DOM, run JS in page |
|
Read cookies, localStorage, sessionStorage | Yes — |
Capture HTTP request/response bodies | Via the MITM proxy (4 KB preview cap by default; |
Modify requests in-flight (headers, body, mock, drop) | Yes (declarative rules, hot-reload) |
Upstream proxy chaining (geo, auth) | Global + per-host upstreams across all clients (SOCKS4/5, HTTP, HTTPS, PAC) |
TLS fingerprint capture (JA3/JA4/JA3S) | Yes |
JA3 + HTTP/2 fingerprint spoofing | Proxy-side (impit re-issues matching requests with spoofed TLS 1.3, HTTP/2 frames, and header order) |
Intercept non-browser traffic (curl, Python, Docker containers) | Yes (interceptors) |
Human-like mouse/keyboard/scroll input |
|
Locator-based interaction |
|
Standard flow:
Call
proxy_startOptionally enable outbound fingerprint spoofing for cross-origin sub-resources:
proxy_set_fingerprint_spoof --preset chrome_136Call
interceptor_browser_launch --url "https://example.com"Drive the page:
interceptor_browser_navigate,interceptor_browser_snapshot,humanizer_click --selector "...",humanizer_type --text "..."Inspect traffic:
proxy_search_traffic --query "<hostname>"
Tools Reference
Lifecycle (4)
Tool | Description |
| Start MITM proxy, auto-generate CA cert |
| Stop proxy (traffic/cert retained). Deactivates this MCP session's interceptor targets; |
| Running state, port, rule/traffic counts |
| CA certificate PEM + SPKI fingerprint |
Upstream Proxy (4)
Tool | Description |
| Set global upstream proxy |
| Remove global upstream |
| Per-host upstream override |
| Remove per-host override |
Interception Rules (7)
Tool | Description |
| Add rule with matcher + handler |
| Modify existing rule |
| Delete rule |
| List all rules by priority |
| Test which rules would match a simulated request or captured exchange, with detailed diagnostics |
| Enable a disabled rule |
| Disable without removing |
Quick debugging examples:
# Simulate a request and see which rule would win
proxy_test_rule_match --mode simulate --request '{"method":"GET","url":"https://example.com/api/v1/items","headers":{"accept":"application/json"}}'
# Evaluate a real captured exchange by ID
proxy_test_rule_match --mode exchange --exchange_id "ex_abc123"Traffic Capture (4)
Tool | Description |
| Paginated traffic list with filters |
| Full exchange details by ID |
| Full-text search across traffic |
| Clear capture buffer |
Modification Shortcuts (3)
Tool | Description |
| Add/overwrite/delete headers on matching traffic (set value to |
| Rewrite request URLs |
| Return mock response for matched requests |
TLS Fingerprinting (9)
Tool | Description |
| Get JA3/JA4 client fingerprints + JA3S for a single exchange |
| List unique JA3/JA4 fingerprints across all traffic with counts |
| Legacy: enable JA3 spoofing (deprecated, use |
| Disable fingerprint spoofing |
| Return current TLS config (server capture, JA3 spoof state) |
| Toggle server-side JA3S capture (monkey-patches |
| Enable full TLS + HTTP/2 fingerprint spoofing via impit. Supports browser presets. |
| List available browser fingerprint presets (e.g. |
| Check fingerprint spoofing backend readiness |
Fingerprint spoofing works by re-issuing the request from the proxy via impit (native Rust TLS/HTTP2 impersonation via rustls). TLS 1.3 and HTTP/2 fingerprints (SETTINGS, WINDOW_UPDATE, PRIORITY frames) match real browsers by construction. The origin server sees the proxy's spoofed TLS, HTTP/2, and header order — not the original client's. When a user_agent is set (including via presets), proxy-mcp also normalizes Chromium UA Client Hints headers (sec-ch-ua*) to match the spoofed User-Agent (forwarding contradictory hints is a common bot signal). Browser exception: when cloakbrowser is launched via interceptor_browser_launch, document loads and same-origin requests use the browser's native TLS (no impit), preserving fingerprint consistency for bot detection challenges. Only cross-origin sub-resource requests are re-issued with spoofed TLS. Non-browser clients (curl, spawn, HAR replay) get full TLS + UA spoofing on all requests. Use proxy_set_fingerprint_spoof with a browser preset for one-command setup. proxy_set_ja3_spoof is kept for backward compatibility but custom JA3 strings are ignored (the preset's impit browser target is used instead). JA4 fingerprints are captured (read-only) but spoofing is not supported.
Interceptors (10)
Interceptors configure targets (browsers, processes, containers) to route their traffic through the proxy automatically.
Discovery (3)
Tool | Description |
| List all interceptors with availability and active target counts |
| Detailed status of a specific interceptor |
| Emergency cleanup: kill all active interceptors across all types |
Browser (3)
Tool | Description |
| Launch cloakbrowser (stealth Chromium) with proxy flags, SPKI cert trust, built-in humanize mode |
| Navigate the bound page via Playwright |
| Close a browser instance by target ID |
Stealth is source-level: cloakbrowser ships 48+ C++ patches so ja3n/ja4/akamai match real Chrome, navigator.webdriver is false, audio/canvas/WebGL fingerprints match real hardware. No JS stealth injection needed. First launch downloads a ~200 MB Chromium binary (cached afterwards).
Terminal / Process (2)
Tool | Description |
| Spawn a command with proxy env vars pre-configured (HTTP_PROXY, SSL certs, etc.) |
| Kill a spawned process and retrieve stdout/stderr |
Sets 18+ env vars covering curl, Node.js, Python requests, Deno, Git, npm/yarn.
Docker (2)
Tool | Description |
| Inject proxy env vars and CA cert into running container |
| Remove proxy config from container |
Two modes: exec (live injection, existing processes need restart) and restart (stop + restart container). Uses host.docker.internal for proxy URL.
Browser DevTools-equivalents (12)
Playwright-driven tools for the browser target. Each takes a target_id directly — no session binding, no sidecar.
Tool | Description |
| ARIA/role YAML snapshot of the page (or selector subtree) — optimized for LLM page reasoning |
| Screenshot. Writes to |
| Buffered console messages since launch, with type/text filters and pagination |
| Cookie listing with filters, pagination, truncated value previews |
| Get one cookie by |
| localStorage/sessionStorage key listing with value previews |
| Get one storage value by |
| Header field listing from proxy-captured traffic since the browser was launched |
| Get one full header field value by |
| Run a JS file in the page (file body wrapped as |
| Inject a JS file as |
| Append a |
Network data is sourced from the MITM proxy rather than a browser-side protocol — the proxy sees every wire request regardless of what the browser reported.
Stealth tradeoffs for JS injection:
Method | Cloakbrowser |
| Safe (isolated utility world) — rate-limit before reCAPTCHA, each call is CDP traffic |
| Best for stealth — pre-document, no DOM artifact |
| Detectable (DOM node, MutationObserver, CSP) |
References: Playwright evaluate, Playwright addInitScript.
Worlds and isolation — what your JS can and can't see
Playwright's evaluate runs in an isolated "utility" world that shares globals with the page's main world. An addInitScript patch to navigator.webdriver is visible to (a) your subsequent evaluate probes AND (b) anti-bot code the site loads. This is the model most "stealth playbooks" assume. Detection vectors are CDP-side (Runtime.evaluate chatter) — cloakbrowser's C++ patches mitigate those.
Practical rules:
Use case | Tool |
Read DOM / extract data |
|
Modify page state, click via JS |
|
Spoof navigator / window fingerprints |
|
Load a 3rd-party JS lib into the page |
|
Sessions (14)
Persistent, queryable on-disk capture for long runs and post-crash analysis.
Tool | Description |
| Start persistent session capture (preview or full-body mode) |
| Stop and finalize the active persistent session |
| Runtime status for persistence (active session, bytes, disk cap errors) |
| Import a HAR file from disk into a new persisted session |
| List recorded sessions from disk |
| Get manifest/details for one session |
| Indexed query over recorded exchanges |
| Search request/response bodies stored in a persistent session, with context snippets |
| Report JA3/JA4/JA3S handshake metadata availability for session entries |
| Fetch one exchange from a session (with optional full bodies) |
| Dry-run or execute replay of selected session requests |
| Export full session or filtered subset to HAR |
| Delete a stored session |
| Rebuild indexes from records after unclean shutdown |
proxy_get_session_exchange and proxy_export_har automatically decompress response bodies (gzip, deflate, brotli) based on the stored content-encoding header. The returned responseBodyText and responseBodyBase64 contain the decompressed content. Raw compressed bytes are preserved on disk for exact replay fidelity.
Note on proxy_start with persistence_enabled: true: this auto-creates a session. A subsequent proxy_session_start() call returns the existing active session instead of failing — no need to stop and re-start.
Humanizer — Playwright Input (5)
Human-like browser input via Playwright page.mouse / page.keyboard. Works with browser_* targets from interceptor_browser_launch. Cloakbrowser's own humanize patches apply when enabled at launch.
Tool | Description |
| Move the mouse to |
| Click a locator ( |
| Type text into the focused element via |
| Dispatch one Playwright |
| Simulate idle behavior with mouse micro-jitter and occasional micro-scrolls to defeat idle detection |
All tools require target_id from a prior interceptor_browser_launch. The engine maintains tracked mouse position across calls for coordinate-based move/click/idle behavior.
Behavioral details:
Mouse:
humanizer_movecallspage.mouse.move; locator clicks call Playwright locators and raw-coordinate clicks callpage.mouse.clickTyping:
humanizer_typecallspage.keyboard.type(text, { delay })whendelay_msis provided; no WPM, typo, or bigram model is implemented in proxy-mcpScrolling:
humanizer_scrollsends one wheel event with the requested deltaIdle: Periodic micro-jitter (±3px subtle / ±8px normal) and random micro-scrolls at configurable intensity
Resources
URI | Description |
| Proxy running state and config |
| CA certificate PEM |
| Traffic stats: method/status breakdown, top hostnames, TLS fingerprint stats |
| All interceptor metadata and activation status |
| Persistent session catalog + runtime persistence status |
| Current page URL/title for the most recently launched browser instance |
| Current page state for all active browser instances |
| Aggregate stats for one recorded session (resource template) |
| Time-bucketed request/error timeline (resource template) |
| Top errors/slow exchanges/host error rates (resource template) |
Usage Example
# Start the proxy
proxy_start
# Optional: start persistent session recording
proxy_session_start --capture_profile full --session_name "reverse-run-1"
# Use interceptors to auto-configure targets:
interceptor_browser_launch # Launch stealth browser with proxy
interceptor_spawn --command curl --args '["https://example.com"]' # Spawn proxied process
# Set upstream proxy for geolocation
proxy_set_upstream --proxy_url socks5://user:pass@geo-proxy:1080
# Mock an API response
proxy_mock_response --url_pattern "/api/v1/config" --status 200 --body '{"feature": true}'
# Inject auth headers (set value to null to delete a header)
proxy_inject_headers --hostname "api.example.com" --headers '{"Authorization": "Bearer token123"}'
# View captured traffic
proxy_list_traffic --hostname_filter "api.example.com"
proxy_search_traffic --query "error"
# TLS fingerprinting
proxy_list_tls_fingerprints # See unique JA3/JA4 fingerprints
proxy_set_ja3_spoof --ja3 "771,4865-..." # Spoof outgoing JA3 (for non-browser clients)
proxy_set_fingerprint_spoof --preset chrome_136 --host_patterns '["example.com"]' # Full fingerprint spoof
proxy_list_fingerprint_presets # Available browser presets
# Human-like browser interaction (browser_* target)
humanizer_move --target_id "browser_<id>" --x 500 --y 300
humanizer_click --target_id "browser_<id>" --selector "#login-button"
humanizer_click --target_id "browser_<id>" --role "button" --name "Sign in"
humanizer_type --target_id "browser_<id>" --text "user@example.com" --delay_ms 45
humanizer_scroll --target_id "browser_<id>" --delta_y 300
humanizer_idle --target_id "browser_<id>" --duration_ms 2000 --intensity subtle
# Run / inject JS in the page
interceptor_browser_evaluate --target_id "browser_<id>" --script_path /tmp/probe.js
interceptor_browser_inject_init_script --target_id "browser_<id>" --script_path /tmp/hook.js # applies on next navigation
interceptor_browser_add_script_tag --target_id "browser_<id>" --script_path /tmp/lib.js # DOM-visible — avoid for stealth
# Query/export recorded session
proxy_list_sessions
proxy_query_session --session_id SESSION_ID --hostname_contains "api.example.com"
proxy_export_har --session_id SESSION_IDArchitecture
State:
ProxyManagersingleton manages mockttp server, rules, trafficRule rebuild: Rules must be set before mockttp
start(), so rule changes trigger stop/recreate/restart cycleTraffic capture:
on('request')+on('response')events, correlated by request IDRing buffer: 1000 entries max, body previews capped at 4KB
TLS capture: Client JA3/JA4 from mockttp socket metadata; server JA3S via
tls.connectmonkey-patchTLS spoofing: impit (native Rust TLS/HTTP2 impersonation via rustls); in-process, no container needed
Interceptors: Managed by
InterceptorManager, each type registers independentlyBrowser: cloakbrowser (stealth Chromium, ~200 MB binary auto-downloaded on first launch) driven via Playwright
BrowserContext/PageHumanizer: Singleton engine using Playwright's
page.mouse/page.keyboard, plus local mouse-position tracking for idle jitter
Testing
npm test # All tests (unit + integration)
npm run test:unit # Unit tests only
npm run test:integration # Integration tests
npm run test:e2e # E2E fingerprint tests (requires cloakbrowser + internet)Credits
Core Libraries
Project | Role |
MITM proxy engine, rule system, CA generation | |
Native TLS/HTTP2 fingerprint impersonation (Rust via NAPI-RS) | |
Stealth-patched Chromium with source-level C++ fingerprint patches | |
Browser automation API driving cloakbrowser | |
MCP server framework |
Available Tools
72 toolshumanizer_clickA
Click an element. Pass one of: selector (CSS/XPath), role + optional name, text, label, or raw x+y coords as fallback. Locator-based calls auto-wait for visible.
Inputs: target_id (required), x, y, name, +7 more.
humanizer_idleA
Simulate idle behavior with mouse micro-jitter and occasional micro-scrolls. Keeps the page 'alive' to avoid idle detection by bot-detection scripts.
Inputs: target_id (required), duration_ms (required), intensity.
humanizer_moveB
Move mouse to target coordinates via the backend Playwright page.
Inputs: x (required), y (required), target_id (required).
humanizer_scrollA
Dispatch a wheel event. Raw page.mouse.wheel — single event, not multi-step.
Inputs: delta_y (required), target_id (required), delta_x.
humanizer_typeB
Type text into the focused element via page.keyboard.type.
Inputs: text (required), target_id (required), delay_ms.
interceptor_browser_add_script_tagA
Append a element to the current page (Playwright page.addScriptTag). WARNING: injects a real DOM node visible to MutationObserver, document.scripts, and CSP. Avoid for anti-bot stealth — prefer interceptor_browser_inject_init_script (no DOM node) when you need page-scope execution.
Inputs: target_id (required), script_path (required), script_type.
interceptor_browser_closeA
Close a browser instance launched by interceptor_browser_launch.
Inputs: target_id (required).
interceptor_browser_evaluateA
Execute a JS file in the page and return its result. Source is loaded from script_path (absolute path). The file body is wrapped in an arrow function receiving __args (so the file may return value; directly and access the optional args object). Runs in Playwright's isolated utility world (different window, same DOM). Reads are invisible to the page; mutations to shared prototypes/globals are observable by page scripts. For main-world patching use interceptor_browser_inject_init_script. Rate-limit before reCAPTCHA: each call emits CDP traffic that behavioural scorers count.
Inputs: target_id (required), script_path (required), args, value_max_chars.
interceptor_browser_get_cookieA
Get one cookie by cookie_id with full value (subject to a hard cap to keep output bounded).
Inputs: cookie_id (required), target_id (required), value_max_chars.
interceptor_browser_get_network_fieldB
Get one full header field value from proxy-captured traffic by field_id.
Inputs: field_id (required), target_id (required), value_max_chars.
interceptor_browser_get_storage_valueB
Get one localStorage/sessionStorage value by item_id.
Inputs: item_id (required), target_id (required), storage_type (required), origin, +1 more.
interceptor_browser_inject_init_scriptA
Inject a JS file as an init script (Playwright page.addInitScript). Runs before any page script on every subsequent navigation/frame. Runs in the isolated utility world — no DOM artifact; patches to shared prototypes/globals reach the page main world via utility-world sharing. Does NOT affect the currently loaded document — navigate again to apply.
Inputs: target_id (required), script_path (required).
interceptor_browser_launchA
Launch cloakbrowser (stealth Chromium) with proxy flags and SPKI certificate trust. Built-in source-level fingerprint patches + humanize mode. Driven via Playwright — locator-based tools replace CDP.
Inputs: url, locale, headless, humanize, +4 more.
interceptor_browser_list_consoleB
List console messages buffered since the browser was launched. Types: log, info, warning, error, debug, etc.
Inputs: target_id (required), limit, types, offset, +1 more.
interceptor_browser_list_cookiesB
List cookies from the browser context with pagination and truncated value previews.
Inputs: target_id (required), full, sort, limit, +5 more.
interceptor_browser_list_network_fieldsA
List request/response header fields from proxy-captured traffic since the browser was launched, with pagination and truncation.
Inputs: target_id (required), limit, offset, direction, +6 more.
interceptor_browser_list_storage_keysA
List localStorage/sessionStorage keys for the current origin with pagination and truncated value previews.
Inputs: target_id (required), storage_type (required), limit, offset, +3 more.
interceptor_browser_screenshotA
Take a screenshot of the bound page. Saves to file_path if provided; otherwise reports byte count without embedding the image.
Inputs: target_id (required), format, quality, file_path, +1 more.
interceptor_browser_snapshotA
Take an ARIA accessibility snapshot of the bound page (YAML-formatted role tree). Great for LLM-driven page understanding without parsing HTML.
Inputs: target_id (required), mode, selector.
interceptor_deactivate_allA
Kill ALL active interceptors across all types. Emergency cleanup — stops all browser instances, kills spawned processes, cleans Docker.
Inputs: no named parameters.
interceptor_docker_attachA
Inject proxy env vars and CA certificate into a Docker container. Two modes: 'exec' (inject into running container) or 'restart' (stop + restart with proxy config).
Inputs: container_id (required), mode.
interceptor_docker_detachA
Remove proxy configuration from a Docker container and clean up injected files.
Inputs: target_id (required).
interceptor_killA
Kill a spawned process by target ID. Also retrieves final stdout/stderr output.
Inputs: target_id (required).
interceptor_listA
List all interceptors with their availability and active targets. Shows the Browser, Terminal and Docker interceptors.
Inputs: no named parameters.
interceptor_spawnA
Spawn a command with proxy env vars pre-configured (HTTP_PROXY, HTTPS_PROXY, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, CURL_CA_BUNDLE, and 15+ more). Traffic automatically routes through the MITM proxy.
Inputs: command (required), cwd, env, args.
interceptor_statusB
Get detailed status of a specific interceptor, including all active targets and their details.
Inputs: interceptor_id (required).
proxy_add_ruleB
Add an interception rule with a matcher and handler. Rules are evaluated by priority (ascending), first match wins.
Inputs: handler (required), matcher (required), description (required), priority.
proxy_check_fingerprint_runtimeA
Check fingerprint spoofing backend readiness without sending traffic.
Inputs: no named parameters.
proxy_clear_ja3_spoofB
Disable fingerprint spoofing.
Inputs: no named parameters.
proxy_clear_trafficA
Clear all captured traffic from the buffer.
Inputs: no named parameters.
proxy_clear_upstreamA
Remove the global upstream proxy. Traffic will go directly to target servers.
Inputs: no named parameters.
proxy_delete_sessionA
Delete a recorded session from disk.
Inputs: session_id (required).
proxy_disable_ruleA
Disable an interception rule without removing it.
Inputs: rule_id (required).
proxy_enable_ruleA
Enable a disabled interception rule.
Inputs: rule_id (required).
proxy_enable_server_tls_captureA
Toggle server-side JA3S capture. When enabled, outgoing TLS connections are intercepted to extract the server's negotiated TLS parameters.
Inputs: enabled (required).
proxy_export_harC
Export a recorded session (or filtered subset) to HAR format.
Inputs: session_id (required), sort, text, to_ts, +7 more.
proxy_get_ca_certA
Get the CA certificate PEM and SPKI fingerprint for installing on the target device.
Inputs: format.
proxy_get_exchangeB
Get full details of a captured HTTP exchange including headers and body previews.
Inputs: exchange_id (required).
proxy_get_sessionB
Get manifest/details for a specific recorded session.
Inputs: session_id (required).
proxy_get_session_exchangeB
Get one exchange from a recorded session by seq or exchange ID.
Inputs: session_id (required), seq, exchange_id, include_body.
proxy_get_session_handshakesC
Summarize TLS handshake/fingerprint availability (JA3/JA4/JA3S) for session exchanges.
Inputs: session_id (required), sort, limit, offset, +2 more.
proxy_get_tls_configA
Get current TLS capture and spoofing configuration.
Inputs: no named parameters.
proxy_get_tls_fingerprintsA
Get JA3/JA4 client fingerprints and JA3S server fingerprint for a specific captured exchange.
Inputs: exchange_id (required).
proxy_import_harA
Import a HAR file from disk into a new persisted session for querying, findings, and replay.
Inputs: har_file (required), strict, max_disk_mb, storage_dir, +1 more.
proxy_inject_headersA
Add or overwrite headers on matching traffic. Creates a passthrough rule with header transforms.
Inputs: headers (required), hostname, priority, direction, +1 more.
proxy_list_fingerprint_presetsA
List available browser fingerprint presets for use with proxy_set_fingerprint_spoof.
Inputs: no named parameters.
proxy_list_rulesA
List all interception rules sorted by priority.
Inputs: no named parameters.
proxy_list_sessionsA
List recorded sessions in storage.
Inputs: no named parameters.
proxy_list_tls_fingerprintsB
List unique client JA3/JA4 fingerprints across captured traffic with occurrence counts.
Inputs: limit, hostname_filter.
proxy_list_trafficB
List captured HTTP exchanges with optional filters. Returns paginated results.
Inputs: limit, offset, url_filter, method_filter, +2 more.
proxy_mock_responseC
Return a mock response for matched requests. Creates a mock rule.
Inputs: status (required), body, method, hostname, +3 more.
proxy_query_sessionA
Query indexed session exchanges by metadata (URL, hostname, method, status) with filters and pagination. Does NOT search body content — use proxy_search_session_bodies for that.
Inputs: session_id (required), sort, text, limit, +7 more.
proxy_remove_host_upstreamA
Remove a per-host upstream proxy override.
Inputs: hostname (required).
proxy_remove_ruleC
Delete an interception rule.
Inputs: rule_id (required).
proxy_replay_sessionB
Replay selected requests from a recorded/imported session. Default mode is dry_run for safety.
Inputs: session_id (required), mode, sort, text, +11 more.
proxy_rewrite_urlB
Rewrite request URLs matching a pattern. Creates a passthrough rule with body match-replace on the URL.
Inputs: replace_with (required), match_pattern (required), hostname, priority.
proxy_search_session_bodiesA
Search inside HTTP request/response bodies stored in a persistent session. Decompresses and searches actual body content — useful for finding specific text, prices, API responses, error messages, etc. in recorded traffic. Returns context snippets around each match (like grep -C).
Inputs: text (required), session_id (required), limit, method, +8 more.
proxy_search_trafficA
Full-text search across URLs, headers, and body previews of captured traffic.
Inputs: query (required), limit.
proxy_session_recoverA
Rebuild session indexes from records after crash/corruption.
Inputs: session_id.
proxy_session_startB
Start persistent on-disk capture for the current proxy run.
Inputs: max_disk_mb, storage_dir, session_name, capture_profile.
proxy_session_statusA
Get current persistent capture runtime status.
Inputs: no named parameters.
proxy_session_stopA
Stop persistent on-disk capture and finalize the active session.
Inputs: no named parameters.
proxy_set_fingerprint_spoofA
Enable outgoing TLS + HTTP/2 fingerprint spoofing via impit (native TLS impersonation, no Docker required). Supports browser presets that select an impit target (rustls, matching real Chrome/Firefox).
Inputs: preset, user_agent, host_patterns, disable_redirect, +1 more.
proxy_set_host_upstreamA
Set a per-host upstream proxy override. Traffic to this hostname will use the specified proxy instead of the global one.
Inputs: hostname (required), proxy_url (required), no_proxy.
proxy_set_ja3_spoofA
Legacy: enable fingerprint spoofing (deprecated, use proxy_set_fingerprint_spoof with a preset). The ja3 parameter is accepted but ignored — the default Chrome preset is used.
Inputs: ja3 (required), user_agent, host_patterns.
proxy_set_upstreamB
Set a global upstream proxy for all outgoing traffic. Supports socks4://, socks5://, http://, https://, and pac+http:// URLs.
Inputs: proxy_url (required), no_proxy.
proxy_startA
Start the HTTPS MITM proxy. Auto-generates a CA certificate. Returns port, URL, cert fingerprint, and setup instructions for the target device.
Inputs: port, max_disk_mb, storage_dir, session_name, +2 more.
proxy_statusA
Get proxy running state, port, upstream config, rule count, and traffic count.
Inputs: no named parameters.
proxy_stopA
Stop the MITM proxy. Traffic history and CA certificate are retained. Interceptor targets (browsers, containers, spawned processes) activated by THIS MCP session are deactivated; targets belonging to other MCP sessions keep running, though the proxy they were pointed at is gone until someone calls proxy_start again. Pass all=true to deactivate every session's targets (the pre-3.5.3, process-wide behaviour). Over stdio there is one session, so every target is deactivated either way.
Inputs: all.
proxy_test_rule_matchA
Test which interception rules would match a request, with detailed per-field pass/fail diagnostics and effective winner by priority.
Inputs: mode, request, exchange_id, limit_rules, +1 more.
proxy_update_ruleC
Modify an existing interception rule.
Inputs: rule_id (required), handler, matcher, priority, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 72 tools
Tools are mostly grouped by clear domains (proxy, session, interceptor, humanizer, fingerprinting), and descriptions clarify near-neighbor cases like traffic search vs session body search. However, some pairs could still be confused, such as proxy_get_exchange vs proxy_get_session_exchange vs interceptor_browser_get_network_field, and the convenience rule creators overlap conceptually with proxy_add_rule.
The naming follows a strong snake_case verb_noun pattern with consistent prefixes like proxy_, interceptor_browser_, and humanizer_. Minor inconsistencies exist: clear vs remove for upstreams, the deprecated proxy_set_ja3_spoof alongside proxy_set_fingerprint_spoof, and proxy_enable_server_tls_capture described as a toggle despite its name.
72 tools is a very large surface for an MCP server, even for a broad proxy/interception platform. Many tools are highly specialized and could be consolidated, such as convenience rule wrappers, session query variants, and the deprecated JA3 tool.
The toolset covers the full proxy lifecycle: start/stop/status, CA management, upstream configuration, rules, traffic capture and search, sessions, HAR import/export, TLS fingerprinting, browser automation, humanization, and process/Docker interception. There are no major workflow dead ends; list-style tools fill gaps where dedicated getters are absent.
Maintenance
Related MCP Connectors
Capture, inspect & debug HTTPS traffic across iOS, Android, browsers & backends — 304 MCP tools.
AI-native mock API server with MCP. Create REST/SOAP mocks from Claude, Cursor, or Windsurf.
Secure tunneling, reverse proxy and remote access for local applications.
Keyless webhook endpoints: capture, wait, replay, forward, and generate types from real traffic.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to capture and analyze HTTP/HTTPS traffic from Android devices. It supports smart searching of network requests and provides tools for detailed traffic analysis via natural language.11245MIT
- AlicenseAqualityDmaintenanceMCP server for intercepting and mocking HTTP(S) traffic via a Mockttp proxy, with tools for Android emulator setup, traffic inspection, protobuf analysis, and rule-based manipulation.35MIT
- FlicenseBqualityDmaintenanceA lightweight MCP server built on mitmproxy that lets LLMs capture, inspect, replay, and modify HTTP traffic through a set of focused tools.138-
- AlicenseAqualityBmaintenanceRuns a local HTTPS MITM proxy to intercept and mock network traffic from Android devices at the network level, enabling AI agents to register JSON transform rules and static responses without modifying app source code.2116 npmMIT