Proxy

You deploy and use proxy-mcp to act as an explicit HTTP/HTTPS MITM proxy that captures, inspects, and mutates traffic, while offering TLS fingerprinting and interceptors to route diverse clients through the proxy. It is designed to be practical for developers who want wire-level traffic control, replay, and traffic orchestration across browsers, CLIs, containers, and mobile apps.

How to use

Learn how to run proxy-mcp in a local environment and connect your tools to it. You start the proxy, optionally begin a persistent session, then configure your devices or interceptors to direct traffic through the proxy. You can also set global or per-host upstream proxies, mock responses, and inspect captured traffic. This guide focuses on practical usage patterns to achieve end-to-end traffic capture, manipulation, and replay.

How to install

Install and prepare the environment, then run the MCP server executable as described by the provided commands and configuration examples.

npm install
npm run build

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

Configuration and usage notes

The proxy exposes a set of lifecycle, interception, and traffic tools. You can start the proxy, inspect status, manage upstream proxies, define interception rules, and query captured traffic. Use the provided commands to start, stop, and inspect the proxy, then apply rules or inject headers as needed.

Notes on security and deployment

The proxy generates its own CA certificate for TLS interception and requires trust in that certificate on target devices or browsers. TLS fingerprinting is captured for client connections, while JA3 spoofing can be enabled per your needs. Interceptors provide safe, scoped routing of Chrome, CLI tools, Docker, and Android devices through the proxy.

Troubleshooting and tips

If traffic isn’t visible, confirm the target is configured to route through the proxy and that NO_PROXY settings don’t bypass it. Ensure the CA cert is trusted on clients. If you encounter issues with DevTools or interceptors, verify the correct target bindings and that the sidecar/DevTools components are installed when required.

Usage examples

Start the proxy, optionally begin a persistent session, and route a client through the proxy using interceptors or direct proxy configuration. Then view captured traffic, inject headers, or apply mock responses to matched requests.

Available tools

proxy_start

Start MITM proxy, auto-generate CA cert

proxy_stop

Stop proxy (traffic/cert retained)

proxy_status

Running state, port, rule/traffic counts

proxy_get_ca_cert

CA certificate PEM + SPKI fingerprint

proxy_set_upstream

Set global upstream proxy

proxy_clear_upstream

Remove global upstream

proxy_set_host_upstream

Per-host upstream override

proxy_remove_host_upstream

Remove per-host upstream override

proxy_add_rule

Add rule with matcher + handler

proxy_update_rule

Modify existing rule

proxy_remove_rule

Delete rule

proxy_list_rules

List all rules by priority

proxy_test_rule_match

Test which rules would match a simulated request or captured exchange, with detailed diagnostics

proxy_enable_rule

Enable a disabled rule

proxy_disable_rule

Disable without removing

proxy_list_traffic

Paginated traffic list with filters

proxy_get_exchange

Full exchange details by ID

proxy_search_traffic

Full-text search across traffic

proxy_clear_traffic

Clear capture buffer

proxy_inject_headers

Add/overwrite/delete headers on matching traffic

proxy_rewrite_url

Rewrite request URLs

proxy_mock_response

Return mock response for matched requests

proxy_get_tls_fingerprints

Get JA3/JA4 client fingerprints + JA3S for a single exchange

proxy_list_tls_fingerprints

List unique JA3/JA4 fingerprints across all traffic with counts

proxy_set_ja3_spoof

Enable JA3 spoofing via CycleTLS for outgoing requests

proxy_clear_ja3_spoof

Disable JA3 spoofing and shut down CycleTLS

proxy_get_tls_config

Return current TLS config (server capture, JA3 spoof state)

proxy_enable_server_tls_capture

Toggle server-side JA3S capture (monkey-patches tls.connect)

interceptor_chrome_launch

Launch Chrome with proxy flags and SPKI cert trust

interceptor_chrome_cdp_info

Get CDP endpoints for a launched Chrome

interceptor_chrome_navigate

Navigate a tab via CDP and verify proxy capture

interceptor_chrome_close

Close a Chrome instance by target ID

interceptor_spawn

Spawn a command with proxy env vars pre-configured

interceptor_kill

Kill a spawned process and retrieve stdout/stderr

interceptor_android_devices

List connected Android devices via ADB

interceptor_android_activate

Full interception: inject CA cert, ADB reverse tunnel, optional Wi-Fi proxy

interceptor_android_deactivate

Remove ADB tunnel and clear Wi-Fi proxy

interceptor_android_setup

Quick setup: push CA cert + ADB reverse tunnel

interceptor_frida_attach

Attach to app and inject SSL unpinning + proxy redirect scripts

interceptor_docker_attach

Inject proxy env vars and CA cert into running container

interceptor_docker_detach

Remove proxy config from container

interceptor_chrome_devtools_pull_sidecar

Install/pull chrome-devtools-mcp sidecar for full DevTools bridge actions

interceptor_chrome_devtools_attach

Start a bound DevTools sidecar session for one Chrome interceptor target

interceptor_chrome_devtools_navigate

Navigate via bound DevTools session and verify matching proxy traffic

interceptor_chrome_devtools_snapshot

Get accessibility snapshot from bound DevTools session

interceptor_chrome_devtools_list_network

List network requests from bound DevTools session

interceptor_chrome_devtools_list_console

List console messages from bound DevTools session

interceptor_chrome_devtools_screenshot

Capture screenshot from bound DevTools session

interceptor_chrome_devtools_detach

Close one bound DevTools sidecar session

proxy_session_start

Start persistent session capture

proxy_session_stop

Stop and finalize the active persistent session

proxy_session_status

Runtime status for persistence

proxy_list_sessions

List recorded sessions from disk

proxy_get_session

Get manifest/details for one session

proxy_query_session

Indexed query over recorded exchanges

proxy_get_session_exchange

Fetch one exchange from a session

proxy_export_har

Export session to HAR