mitmproxy-mcp
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., "@mitmproxy-mcp Start proxy, set scope to example.com, and get traffic summary."
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.
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/500error.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-cffito 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-cffito 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-cffiautomation 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.gitThen 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. Withweb=True(or anyweb_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-loopbackhostorweb_hostneeds--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 acurlequivalent 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, orblock.phase:requestorresponse.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.
Initialize the Proxy:
{"method": "tools/call", "params": {"name": "start_proxy", "arguments": {"port": 8080}}}Intercept & Block:
{"method": "tools/call", "params": {"name": "add_interception_rule", "arguments": {"rule_id": "block-ads", "action_type": "block", "url_pattern": ".*analytics.*"}}}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_scopeimmediately. 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_flowtool usescurl-cffispecifically 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 toolsadd_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
Scored across 25 tools
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.
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.
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.
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
Related MCP Connectors
Debug webhooks from your AI agent: inspect and replay captured webhooks on localhost.
Anonymous webhook capture, inspection, waiting, and response configuration for AI agents.
Capture, inspect, send and assert on webhooks and inbound email from your coding agent.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to interact with Charles Proxy for HTTP traffic analysis, supporting incremental harvest, checkpoint timelines, and rich filtering tools.138MIT
- FlicenseBqualityDmaintenanceA lightweight MCP server built on mitmproxy that lets LLMs capture, inspect, replay, and modify HTTP traffic through a set of focused tools.138-
- FlicenseNot gradedqualityDmaintenanceEnables Claude Code to inspect, modify, and block HTTP traffic via mitmproxy, with tools for flow capture, filtering, and rule creation.1-
- AlicenseBqualityBmaintenanceEnables AI agents to connect to Charles Proxy for live and historical traffic analysis, summary-first insights, request detail inspection, and data-driven mock creation via Map Local/Remote.47MIT