Skip to main content
Glama

mitmproxy MCP Server

A Model Context Protocol (MCP) server that transforms mitmproxy into a powerful toolset for AI agents. This allows LLMs (like Claude, GPT-4, or local models) to inspect, modify, and replay HTTP/HTTPS traffic in real-time.

New in this build (the fun stuff)

This project has grown beyond simple capture + replay. You can now:

  • Search traffic quickly with filters by domain/method/body text.

  • Extract data from responses using JSONPath or CSS selectors.

  • Use session variables to grab tokens from one response and reuse them in later replays.

  • Run lightweight fuzzing against query params or JSON body fields for quick DAST checks.

  • Reconstruct API patterns and export an OpenAPI-style spec from captured traffic.

  • Detect auth patterns (Bearer/JWT/API key/session cookie/CSRF/OAuth hints).

  • Generate starter scraper code from real captured flows.

Related MCP server: mitmproxy-mcp

Why use this?

Standard "web search" or "fetch" tools are stateless and easily detected. mitmproxy-mcp provides:

  • Deep Debugging: The agent can inspect full request/response cycles (headers, payloads, cookies) to identify why a frontend is failing or why an API is returning a 4xx/500 error.

  • API Reverse Engineering: Let the LLM observe undocumented internal APIs, map out JSON schemas, and generate client libraries or documentation automatically.

  • Automated Security Testing: Perform DAST (Dynamic Application Security Testing) by allowing the agent to inject payloads into specific parameters and analyze the response.

  • Live Interception: Modify traffic on the fly: inject headers, mock responses for testing, or block tracking pixels to reduce noise.

  • Stealth Replay: Uses curl-cffi to mimic Chrome/Safari TLS fingerprints, bypassing basic anti-bot measures that standard Python libraries trigger.

Key Features

  • Lifecycle Control: Start and stop the mitmproxy instance directly from the LLM.

  • Deep Inspection: Capture full request/response cycles, including headers, bodies, and timing.

  • Traffic Search & Filtering: Scope by domain, then search flows by query/method so context stays clean.

  • Active Interception: Dynamic rules to inject headers, replace body content via regex, or block requests.

  • Stealth Replay: Re-execute flows using curl-cffi to impersonate modern browser TLS fingerprints (e.g., Chrome).

  • Session-Aware Workflows: Extract dynamic values (like CSRF tokens) and re-inject them into replayed traffic.

  • Response Data Extraction: Pull structured values from HTML/JSON responses via CSS selectors and JSONPath.

  • API Discovery: Group similar endpoints, identify path/query params, and export OpenAPI JSON.

  • Security Recon Helpers: Detect common auth patterns and run targeted fuzz payloads.

  • Scraper Bootstrapping: Generate executable curl-cffi automation code from observed traffic.

Quickstart

Option 1: Using uvx (Recommended)

Add this to your MCP client configuration (e.g., Claude Desktop, Cursor, or AntiGravity):

{
  "mcpServers": {
    "mitmproxy-mcp": {
      "command": "uvx",
      "args": ["mitmproxy-mcp"]
    }
  }
}

Option 2: From a Cloned Repository

If you want to run from a local clone (useful for development or testing unreleased changes):

git clone https://github.com/snapspecter/mitmproxy-mcp.git

Then add this to your MCP client configuration, replacing the path with your clone location:

{
  "mcpServers": {
    "mitmproxy-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mitmproxy-mcp", "mitmproxy-mcp"]
    }
  }
}

Installation

Option 1: Global Install (with uv)

uv tool install mitmproxy-mcp

Option 2: Docker (Isolated Environment)

# Build and run
docker build -t mitmproxy-mcp .
docker run -p 8080:8080 mitmproxy-mcp

Option 3: Manual Pip Install

python -m venv venv
source venv/bin/activate
pip install mitmproxy-mcp

Available Tools

Lifecycle & Configuration

  • start_proxy(port=8080, host="127.0.0.1", web=False, web_port=8081, web_host="127.0.0.1"): Starts the mitmproxy server. With web=True (or any web_port / web_host) it also serves the mitmweb UI, and the result carries the UI URL with a random per-start access token, unless a static password is set with --web-password / MITMPROXY_WEB_PASSWORD (plaintext, or an argon2 hash starting with $; prefer the env var, since a flag shows in the process list). Omitted arguments fall back to the server defaults below.

  • Server defaults, as CLI flags or env vars: --port / MITMPROXY_PORT, --host / MITMPROXY_HOST, --web / MITMPROXY_WEB, --web-port / MITMPROXY_WEB_PORT, --web-host / MITMPROXY_WEB_HOST, --auto-start / MITMPROXY_AUTO_START. A non-loopback host or web_host needs --allow-remote-bind / MITMPROXY_ALLOW_REMOTE_BIND. The proxy and web UI must use different ports.

  • stop_proxy(): Shuts down the proxy.

  • set_scope(allowed_domains): Filters recorded traffic (e.g., ["api.github.com", "example.com"]).

  • list_tools(): Returns all exposed MCP tools and input schemas.

Inspection

  • get_traffic_summary(limit=20): Returns a list of recent network flows.

  • inspect_flow(flow_id): Provides full details and a curl equivalent for a specific flow.

  • search_traffic(query, domain, method, limit=50): Filter captured traffic by keyword/domain/method.

  • clear_traffic(): Clears persisted traffic history.

Modification & Interception

  • add_interception_rule(rule_id, action_type, ...):

  • action_type: inject_header, replace_body, or block.

  • phase: request or response.

  • set_global_header(key, value): Injects a header into every request.

  • remove_global_header(key): Removes a previously injected global header.

  • list_rules(): Shows currently active interception rules.

  • clear_rules(): Flushes all active interception rules.

Replay

  • replay_flow(flow_id, method, headers_json, body): Re-sends a request with modifications using browser-grade impersonation.

Extraction & Session Variables

  • extract_from_flow(flow_id, json_path=None, css_selector=None): Extract values from captured response bodies.

  • set_session_variable(name, value): Manually set a session variable.

  • extract_session_variable(name, flow_id, regex_pattern, group_index=1): Extract and save a variable from a response body.

Security & API Analysis

  • fuzz_endpoint(flow_id, target_param, param_type, payload_category, timeout=10.0): Replay with payload substitutions and report anomalies.

  • get_api_patterns(domain=None, limit=50): Cluster captured traffic into endpoint patterns.

  • export_openapi_spec(domain=None, limit=50): Produce an OpenAPI v3 JSON spec from captured traffic.

  • detect_auth_pattern(flow_ids=None): Infer likely auth mechanisms from observed requests.

Code Generation

  • generate_scraper_code(flow_ids, target_framework="curl_cffi"): Generate starter scraper/automation code from captured flows.

Programmatic Usage

Note: These are JSON-RPC calls sent by the MCP Host (Client). You do not need to type these manually in the terminal.

  1. Initialize the Proxy: {"method": "tools/call", "params": {"name": "start_proxy", "arguments": {"port": 8080}}}

  2. Intercept & Block: {"method": "tools/call", "params": {"name": "add_interception_rule", "arguments": {"rule_id": "block-ads", "action_type": "block", "url_pattern": ".*analytics.*"}}}

  3. Modify Response: {"method": "tools/call", "params": {"name": "add_interception_rule", "arguments": {"rule_id": "mock-api", "action_type": "replace_body", "url_pattern": ".*user/profile.*", "action_value": "{\"name\": \"AI Agent\"}"}}}

Helpful Tips

  • Manage Context: Use set_scope immediately. LLMs perform poorly when flooded with background OS telemetry.

  • Browser Setup: Ensure your browser or application is configured to use the proxy (usually localhost:8080) and has the mitmproxy CA certificates installed for HTTPS inspection.

  • Stealth: The replay_flow tool uses curl-cffi specifically to avoid being flagged as a bot by services that check TLS fingerprints.

Development

git clone [https://github.com/snapspecter/mitmproxy-mcp.git](https://github.com/snapspecter/mitmproxy-mcp.git)
cd mitmproxy-mcp
uv sync
uv run pytest

License: MIT

Available Tools

25 tools
add_interception_ruleD

Inputs: rule_id (required), action_type (required), key, phase, +4 more. Returns: result

clear_rulesD

Inputs: no named parameters. Returns: result

clear_trafficA

Clear all captured traffic from the database.

Inputs: no named parameters. Returns: result

detect_auth_patternD

Inputs: flow_ids. Returns: result

export_openapi_specA

Exports captured API traffic patterns to an OpenAPI v3 JSON specification. Args: domain: Filter traffic by domain limit: Max number of traffic flows to analyze. None = all flows.

Inputs: limit, domain. Returns: result

extract_from_flowB

Extract specific data from a flow's response body using JSONPath or CSS selectors. Args: flow_id: The ID of the captured flow json_path: A JSONPath expression to extract data from a JSON response css_selector: A CSS selector to extract data from an HTML/XML response

Inputs: flow_id (required), json_path, css_selector. Returns: result

extract_session_variableA

Extract a value from a flow's response body using a regex and store it as a session variable. Args: name: Variable name (referenced as $name in replay_flow) flow_id: The ID of the flow to extract from regex_pattern: The regex pattern with capture groups group_index: Which regex capture group to extract (default: 1)

Inputs: name (required), flow_id (required), regex_pattern (required), group_index. Returns: result

fuzz_endpointA

Fuzz an endpoint by substituting a target parameter with a category of DAST payloads. Args: flow_id: The flow to replay as the base request. target_param: The name of the parameter to replace. param_type: The location of the parameter: 'query' or 'json_body'. payload_category: The category of payloads ('sqli', 'xss', 'path_traversal').

Inputs: flow_id (required), param_type (required), target_param (required), payload_category (required), +1 more. Returns: result

generate_scraper_codeB

Generate executable scraper/automation code from a comma-separated list of flow IDs. Args: flow_ids: Comma-separated list of flow IDs to include in the script. target_framework: The framework to generate code for.

Inputs: flow_ids (required), target_framework. Returns: result

get_api_patternsB

Cluster captured traffic into endpoint patterns. Args: domain: Filter traffic by domain limit: Max number of flows to analyze. None = all flows.

Inputs: limit, domain. Returns: result

get_flow_schemaC

Infer a simple schema from a flow's JSON response body.

Inputs: flow_id (required). Returns: result

get_traffic_summaryD

Inputs: limit. Returns: result

inspect_flowA

Get full details of a captured flow. Args: flow_id: The ID of the captured flow full_body: If True, return full request body instead of 2000-char preview

Inputs: flow_id (required), full_body. Returns: result

inspect_flowsA

Batch inspect multiple flows in one call. Reduces context usage vs calling inspect_flow N times. Args: flow_ids: Comma-separated list of flow IDs to inspect fields: Comma-separated list of DB columns to select. e.g. "id,url,method,request_headers,request_body" to skip response data. Default: all columns. full_body: If True, return full request body instead of preview

Inputs: flow_ids (required), fields, full_body. Returns: result

list_rulesD

Inputs: no named parameters. Returns: result

list_toolsA

List all available tools with their descriptions.

Inputs: no named parameters. Returns: result

load_traffic_fileA

Import flows from a HAR or mitmproxy flow file into the traffic database. After import, all traffic inspection tools work on the imported data. No proxy needs to be running. Args: file_path: Path to .har or .mitm/.flow file append: If True, keep existing traffic. If False (default), clear first. scope: Comma-separated list of domains to filter by during import. Only flows matching these domains are imported.

Inputs: file_path (required), scope, append. Returns: result

remove_global_headerD

Inputs: key (required). Returns: result

replay_flowC

Replay a captured flow, optionally with modified method, headers, or body. Supports session variable injection (e.g., $token) in headers and body.

Inputs: flow_id (required), body, method, timeout, +1 more. Returns: result

search_trafficC

Search captured traffic using filters. Args: query: Keywords to search in URL or body domain: Filter by domain name method: Filter by HTTP method (GET, POST, etc.) limit: Max results to return

Inputs: limit, query, domain, method. Returns: result

set_global_headerD

Inputs: key (required), value (required). Returns: result

set_scopeD

Inputs: allowed_domains (required). Returns: result

set_session_variableC

Manually set a session variable to use in replayed flows.

Inputs: name (required), value (required). Returns: result

start_proxyA

Start the mitmproxy instance. Args: port: Port to listen on. Omit to use the server's configured default (--port / MITMPROXY_PORT, else 8080). dump_file: Optional file path to save raw mitmproxy .flow data. Prefix with + to append to an existing file. upstream_proxy: Optional upstream proxy URL (e.g., 'http://user:pass@proxy:port').

Inputs: port, dump_file, upstream_proxy. Returns: result

stop_proxyD

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools target a distinct action or resource: proxy lifecycle, traffic inspection, extraction, replay, rules, and export are clearly separated. The main ambiguities are the blank descriptions for several tools (get_traffic_summary, set_scope, detect_auth_pattern, etc.) and the close relationship between extract_from_flow and extract_session_variable, though their purposes are still distinct.

    Naming Consistency5/5

    Every tool follows a consistent snake_case verb_noun convention: start_proxy/stop_proxy, inspect_flow/inspect_flows, set_scope, clear_traffic, replay_flow, fuzz_endpoint. Even compound operations like export_openapi_spec and generate_scraper_code fit the pattern cleanly. No naming convention mixing or vague single-word verbs exist.

    Tool Count3/5

    At 25 tools, this sits right at the upper boundary of acceptable size for a proxy/HTTP traffic analysis server. The breadth is mostly justified by the many sub-domains (capture, inspection, extraction, replay, rules, export), but several tools have minimal descriptions and could potentially be consolidated. It is not egregiously over-scoped, but it feels heavy.

    Completeness4/5

    The tool surface covers the full proxy workflow: start/stop, traffic capture, import, search, inspection, schema inference, extraction, session variables, replay, fuzzing, code generation, and OpenAPI export. Minor gaps exist such as no per-flow deletion, no rule editing beyond add/list/clear, and no obvious way to export raw traffic back out, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers