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. It also ships "interceptors" to route Chrome, CLI tools, Docker containers, and Android devices/apps through the proxy.

44 tools + 5 resources. Built on mockttp.

Boundaries

• Only sees traffic configured to route through it (not a network tap or packet sniffer)
• Spoofs outgoing JA3 only (via CycleTLS), not JA4 (JA4 is capture-only)
• Can add, overwrite, or delete HTTP headers — does not control header order
• Returns its own CA certificate — does not expose upstream server certificate chains

Pairs well with CDP/Playwright

Use CDP/Playwright for browser internals (DOM, JS execution, localStorage, cookie jar), and proxy-mcp for wire-level capture/manipulation + replay. They complement each other:

A typical combo: launch Chrome via interceptor_chrome_launch (routes through proxy automatically), drive pages with Playwright/CDP, and use proxy-mcp to capture the wire traffic, inject headers, or spoof JA3 — all in the same session.

Attach Playwright to proxy-launched Chrome:

1. Call proxy_start
2. Call interceptor_chrome_launch
3. Call interceptor_chrome_cdp_info (or read proxy://chrome/targets) to get cdp.httpUrl (Playwright) and cdp.browserWebSocketDebuggerUrl (raw CDP clients)
4. In Playwright:

   import { chromium } from "playwright";
   const browser = await chromium.connectOverCDP("http://127.0.0.1:<cdp-port>");
   

Setup

npm install
npm run build

Claude Code .mcp.json

{
  "mcpServers": {
    "proxy": {
      "command": "node",
      "args": ["/path/to/proxy-mcp/dist/index.js"]
    }
  }
}

Tools Reference

Lifecycle (4)

Upstream Proxy (4)

Interception Rules (6)

Traffic Capture (4)

Modification Shortcuts (3)

TLS Fingerprinting (6)

JA3 spoofing works by re-issuing the request from the proxy via CycleTLS with a specified JA3 string. The origin server sees the proxy's spoofed fingerprint, not the original client's. JA4 fingerprints are captured (read-only) but spoofing is not supported.

Interceptors (17)

Interceptors configure targets (browsers, processes, devices, containers) to route their traffic through the proxy automatically.

Discovery (3)

Chrome (3)

Launches with isolated temp profile, auto-cleaned on close. Supports chrome, chromium, brave, edge.

Terminal / Process (2)

Sets 18+ env vars covering curl, Node.js, Python requests, Deno, Git, npm/yarn.

Android ADB (4)

Caveats: CA cert injection requires root access. Supports Android 14+ (/apex/com.android.conscrypt/cacerts/). Wi-Fi proxy is opt-in (default off).

Android Frida (3)

Caveats: Requires frida-server running on device. Uses frida-js (pure JS, no native binaries on host). SSL unpinning covers OkHttp, BoringSSL, TrustManager, system TLS — but may not work against QUIC or custom TLS stacks.

Docker (2)

Two modes: exec (live injection, existing processes need restart) and restart (stop + restart container). Uses host.docker.internal for proxy URL.

Resources

Usage Example

# Start the proxy
proxy_start

# Configure device to use proxy (Wi-Fi settings or interceptors)
# Install CA cert on device (proxy_get_ca_cert)

# Or use interceptors to auto-configure targets:
interceptor_chrome_launch                    # Launch Chrome with proxy
interceptor_spawn --command curl --args '["https://example.com"]'  # Spawn proxied process
interceptor_android_activate --serial DEVICE_SERIAL               # Android device

# 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

Architecture

• State: ProxyManager singleton manages mockttp server, rules, traffic
• Rule rebuild: Rules must be set before mockttp start(), so rule changes trigger stop/recreate/restart cycle
• Traffic capture: on('request') + on('response') events, correlated by request ID
• Ring buffer: 1000 entries max, body previews capped at 4KB
• TLS capture: Client JA3/JA4 from mockttp socket metadata; server JA3S via tls.connect monkey-patch
• Interceptors: Managed by InterceptorManager, each type registers independently

Testing

npm test              # All tests
npm run test:unit     # Unit tests only
npm run test:integration  # Integration tests

Credits

Core Libraries

Vendored Frida Scripts

All scripts in src/frida-scripts/vendor/ are derived from httptoolkit/frida-interception-and-unpinning (MIT):

• config-template.js — proxy/cert config injection
• android-certificate-unpinning.js — TrustManager + OkHttp + BoringSSL hooks
• android-system-certificate-injection.js — runtime cert injection via KeyStore
• android-proxy-override.js — ProxySelector monkey-patch
• native-tls-hook.js — BoringSSL/OpenSSL native hooks
• native-connect-hook.js — libc connect() redirect