Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/snapspecter--mitmproxy-mcp/badge.svg)](/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

i

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.

  1. # mitmproxy MCP Server
  2. 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.
  3. ## New in this build (the fun stuff)
  4. This project has grown beyond simple capture + replay. You can now:
  5. * **Search traffic quickly** with filters by domain/method/body text.
  6. * **Extract data from responses** using JSONPath or CSS selectors.
  7. * **Use session variables** to grab tokens from one response and reuse them in later replays.
  8. * **Run lightweight fuzzing** against query params or JSON body fields for quick DAST checks.
  9. * **Reconstruct API patterns** and export an OpenAPI-style spec from captured traffic.
  10. * **Detect auth patterns** (Bearer/JWT/API key/session cookie/CSRF/OAuth hints).
  11. * **Generate starter scraper code** from real captured flows.
  12. ## Why use this?
  13. Standard "web search" or "fetch" tools are stateless and easily detected. mitmproxy-mcp provides:
  14. * **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.
  15. * **API Reverse Engineering**: Let the LLM observe undocumented internal APIs, map out JSON schemas, and generate client libraries or documentation automatically.
  16. * **Automated Security Testing**: Perform DAST (Dynamic Application Security Testing) by allowing the agent to inject payloads into specific parameters and analyze the response.
  17. * **Live Interception**: Modify traffic on the fly: inject headers, mock responses for testing, or block tracking pixels to reduce noise.
  18. * **Stealth Replay**: Uses `curl-cffi` to mimic Chrome/Safari TLS fingerprints, bypassing basic anti-bot measures that standard Python libraries trigger.
  19. ## Key Features
  20. - **Lifecycle Control**: Start and stop the mitmproxy instance directly from the LLM.
  21. - **Deep Inspection**: Capture full request/response cycles, including headers, bodies, and timing.
  22. - **Traffic Search & Filtering**: Scope by domain, then search flows by query/method so context stays clean.
  23. - **Active Interception**: Dynamic rules to inject headers, replace body content via regex, or block requests.
  24. - **Stealth Replay**: Re-execute flows using `curl-cffi` to impersonate modern browser TLS fingerprints (e.g., Chrome).
  25. - **Session-Aware Workflows**: Extract dynamic values (like CSRF tokens) and re-inject them into replayed traffic.
  26. - **Response Data Extraction**: Pull structured values from HTML/JSON responses via CSS selectors and JSONPath.
  27. - **API Discovery**: Group similar endpoints, identify path/query params, and export OpenAPI JSON.
  28. - **Security Recon Helpers**: Detect common auth patterns and run targeted fuzz payloads.
  29. - **Scraper Bootstrapping**: Generate executable `curl-cffi` automation code from observed traffic.
  30. ## Quickstart
  31. ### Option 1: Using `uvx` (Recommended)
  32. Add this to your MCP client configuration (e.g., Claude Desktop, Cursor, or AntiGravity):
  33. ```json
  34. {
  35. "mcpServers": {
  36. "mitmproxy-mcp": {
  37. "command": "uvx",
  38. "args": ["mitmproxy-mcp"]
  39. }
  40. }
  41. }
  42. ```
  43. ### Option 2: From a Cloned Repository
  44. If you want to run from a local clone (useful for development or testing unreleased changes):
  45. ```bash
  46. git clone https://github.com/snapspecter/mitmproxy-mcp.git
  47. ```
  48. Then add this to your MCP client configuration, replacing the path with your clone location:
  49. ```json
  50. {
  51. "mcpServers": {
  52. "mitmproxy-mcp": {
  53. "type": "stdio",
  54. "command": "uv",
  55. "args": ["run", "--directory", "/path/to/mitmproxy-mcp", "mitmproxy-mcp"]
  56. }
  57. }
  58. }
  59. ```
  60. ## Installation
  61. ### Option 1: Global Install (with `uv`)
  62. ```bash
  63. uv tool install mitmproxy-mcp
  64. ```
  65. ### Option 2: Docker (Isolated Environment)
  66. ```bash
  67. # Build and run
  68. docker build -t mitmproxy-mcp .
  69. docker run -p 8080:8080 mitmproxy-mcp
  70. ```
  71. ### Option 3: Manual Pip Install
  72. ```bash
  73. python -m venv venv
  74. source venv/bin/activate
  75. pip install mitmproxy-mcp
  76. ```
  77. ## Available Tools
  78. ### Lifecycle & Configuration
  79. * `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.
  80. * 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.
  81. * `stop_proxy()`: Shuts down the proxy.
  82. * `set_scope(allowed_domains)`: Filters recorded traffic (e.g., `["api.github.com", "example.com"]`).
  83. * `list_tools()`: Returns all exposed MCP tools and input schemas.
  84. ### Inspection
  85. * `get_traffic_summary(limit=20)`: Returns a list of recent network flows.
  86. * `inspect_flow(flow_id)`: Provides full details and a `curl` equivalent for a specific flow.
  87. * `search_traffic(query, domain, method, limit=50)`: Filter captured traffic by keyword/domain/method.
  88. * `clear_traffic()`: Clears persisted traffic history.
  89. ### Modification & Interception
  90. * `add_interception_rule(rule_id, action_type, ...)`:
  91. * `action_type`: `inject_header`, `replace_body`, or `block`.
  92. * `phase`: `request` or `response`.
  93. * `set_global_header(key, value)`: Injects a header into every request.
  94. * `remove_global_header(key)`: Removes a previously injected global header.
  95. * `list_rules()`: Shows currently active interception rules.
  96. * `clear_rules()`: Flushes all active interception rules.
  97. ### Replay
  98. * `replay_flow(flow_id, method, headers_json, body)`: Re-sends a request with modifications using browser-grade impersonation.
  99. ### Extraction & Session Variables
  100. * `extract_from_flow(flow_id, json_path=None, css_selector=None)`: Extract values from captured response bodies.
  101. * `set_session_variable(name, value)`: Manually set a session variable.
  102. * `extract_session_variable(name, flow_id, regex_pattern, group_index=1)`: Extract and save a variable from a response body.
  103. ### Security & API Analysis
  104. * `fuzz_endpoint(flow_id, target_param, param_type, payload_category, timeout=10.0)`: Replay with payload substitutions and report anomalies.
  105. * `get_api_patterns(domain=None, limit=50)`: Cluster captured traffic into endpoint patterns.
  106. * `export_openapi_spec(domain=None, limit=50)`: Produce an OpenAPI v3 JSON spec from captured traffic.
  107. * `detect_auth_pattern(flow_ids=None)`: Infer likely auth mechanisms from observed requests.
  108. ### Code Generation
  109. * `generate_scraper_code(flow_ids, target_framework="curl_cffi")`: Generate starter scraper/automation code from captured flows.
  110. ## Programmatic Usage
  111. Note: These are JSON-RPC calls sent by the MCP Host (Client). You do not need to type these manually in the terminal.
  112. 1. **Initialize the Proxy**:
  113. `{"method": "tools/call", "params": {"name": "start_proxy", "arguments": {"port": 8080}}}`
  114. 2. **Intercept & Block**:
  115. `{"method": "tools/call", "params": {"name": "add_interception_rule", "arguments": {"rule_id": "block-ads", "action_type": "block", "url_pattern": ".*analytics.*"}}}`
  116. 3. **Modify Response**:
  117. `{"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\"}"}}}`
  118. ## Helpful Tips
  119. * **Manage Context**: Use `set_scope` immediately. LLMs perform poorly when flooded with background OS telemetry.
  120. * **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.
  121. * **Stealth**: The `replay_flow` tool uses `curl-cffi` specifically to avoid being flagged as a bot by services that check TLS fingerprints.
  122. ## Development
  123. ```bash
  124. git clone [https://github.com/snapspecter/mitmproxy-mcp.git](https://github.com/snapspecter/mitmproxy-mcp.git)
  125. cd mitmproxy-mcp
  126. uv sync
  127. uv run pytest
  128. ```
  129. **License:** MIT
  130. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.