mitmproxy-mcp
MCP Server that wraps mitmproxy and exposes it as a tool to any MCP client, allows your AI agents to inspect traffic, filter traffic, intercept & modify traffic, request reply, set global headers, and start/stop mitmproxy as needed.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/snapspecter--mitmproxy-mcp)HTML
<a href="/listings/snapspecter--mitmproxy-mcp"><img src="/api/listings/snapspecter--mitmproxy-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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"]
}
}
}What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 181 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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.
- ## 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):
- ```json
- {
- "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):
- ```bash
- git clone https://github.com/snapspecter/mitmproxy-mcp.git
- ```
- Then add this to your MCP client configuration, replacing the path with your clone location:
- ```json
- {
- "mcpServers": {
- "mitmproxy-mcp": {
- "type": "stdio",
- "command": "uv",
- "args": ["run", "--directory", "/path/to/mitmproxy-mcp", "mitmproxy-mcp"]
- }
- }
- }
- ```
- ## Installation
- ### Option 1: Global Install (with `uv`)
- ```bash
- uv tool install mitmproxy-mcp
- ```
- ### Option 2: Docker (Isolated Environment)
- ```bash
- # Build and run
- docker build -t mitmproxy-mcp .
- docker run -p 8080:8080 mitmproxy-mcp
- ```
- ### Option 3: Manual Pip Install
- ```bash
- 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
- ```bash
- 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
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.