mitmproxy
Interactive HTTPS proxy for debugging and testing
Quick Take: mitmproxy
mitmproxy is the most powerful free HTTP/HTTPS proxy available. The Python scripting API sets it apart from every competitor — the ability to programmatically intercept and modify traffic enables testing and debugging workflows that GUI-only tools can't match. The learning curve is real (especially for the TUI and certificate setup), but once you've spent an hour with it, mitmproxy becomes a permanent part of your toolkit. If you debug APIs, develop mobile apps, or do any kind of security testing, install it.
Best For
- •API developers debugging request/response issues
- •Mobile app developers inspecting network traffic
- •Security researchers and penetration testers
- •Developers who need scriptable traffic modification
Install with Homebrew
brew install --cask mitmproxyWhat is mitmproxy?
mitmproxy is an open-source interactive HTTPS proxy that lets you intercept, inspect, modify, and replay HTTP and HTTPS traffic flowing through your machine. If you've ever needed to see exactly what an API request looks like, debug a mobile app's network calls, test how your backend handles malformed requests, or understand what a third-party SDK is sending home, mitmproxy is the tool. It ships with three interfaces: `mitmproxy` (a terminal-based TUI with vim-style keybindings), `mitmweb` (a browser-based GUI), and `mitmdump` (a headless CLI for scripting and automation). All three use the same proxy engine — you choose the interface that fits your workflow. The TUI is fastest for keyboard-driven developers, the web UI is easiest for visual inspection, and mitmdump is what you want for automated testing pipelines. The 'man-in-the-middle' in the name describes the technical approach: mitmproxy sits between your client (browser, mobile app, CLI tool) and the server, terminating and re-establishing TLS connections so it can read encrypted traffic. You install mitmproxy's CA certificate on your device, and from that point forward, all HTTPS traffic flowing through the proxy is visible in plaintext. This sounds alarming — and it should, because it's exactly what attackers do. But for developers and security researchers, it's an indispensable debugging tool. mitmproxy competes with commercial tools like Proxyman and Charles Proxy on macOS. The commercial tools have prettier GUIs and easier certificate setup. mitmproxy's advantages are that it's free, open-source, scriptable with Python, and significantly more powerful for automated testing and modification of traffic. If you need to write a script that automatically modifies API responses for testing, mitmproxy is the only free tool that does it well.
Deep Dive: How mitmproxy Intercepts HTTPS
A technical look at the TLS interception mechanism that makes mitmproxy possible, and why it matters for developers.
History & Background
mitmproxy was created by Aldo Cortesi in 2010, initially as a tool for security research. The Python-based proxy evolved from a simple HTTP interceptor into a full-featured HTTPS proxy with a TUI, web interface, and scripting API. Maximilian Hils joined the project and has been the primary maintainer for the past several years. The project crossed 37,000 GitHub stars and is used by companies like Google, Mozilla, and many security firms as part of their development and testing workflows.
How It Works
When a client connects to mitmproxy and requests an HTTPS URL, mitmproxy performs a TLS termination: it presents its own certificate (signed by the mitmproxy CA) to the client, completes the TLS handshake, reads the plaintext HTTP request, then opens a new TLS connection to the upstream server and forwards the request. The response follows the same path in reverse. This two-hop architecture means both the request and response are visible to mitmproxy in plaintext. The mitmproxy CA certificate must be trusted by the client — which is why you install it manually on your devices.
Ecosystem & Integrations
mitmproxy's ecosystem includes the core proxy (mitmproxy/mitmweb/mitmdump), a Python API for add-ons, and community-contributed scripts on GitHub. The add-on system is the most powerful feature — you can write Python scripts that intercept any stage of the request/response lifecycle: clientconnect, request, responseheaders, response, error. Community add-ons exist for API mocking, response recording, performance testing, and security scanning.
Future Development
Current development focuses on HTTP/3 (QUIC) support, improved WebSocket inspection, better certificate handling for modern TLS configurations, and performance improvements for high-throughput scenarios. The web interface (mitmweb) is being modernized with a React-based frontend that provides better filtering, search, and flow visualization.
Key Features
Three Interfaces: TUI, Web, CLI
mitmproxy (the TUI) gives you a vim-like interface where you navigate flows with j/k, press Enter to inspect details, Tab between request/response, and use `:` for commands. mitmweb opens a browser-based dashboard with clickable flows, searchable request lists, and formatted JSON/XML views. mitmdump runs headlessly, outputting to stdout or piping to Python scripts. Same engine, three different ways to interact.
HTTPS Interception
mitmproxy generates a CA certificate that you install on your client devices. Once trusted, mitmproxy performs TLS interception — it terminates the client's TLS connection, reads the traffic, and opens a new TLS connection to the upstream server. This lets you inspect encrypted HTTPS traffic in plaintext. Every API call, every header, every cookie, every request body is visible.
Python Scripting API
mitmproxy's scripting API lets you write Python scripts that modify traffic in real time. Intercept requests and change headers before they reach the server. Modify responses before they reach the client. Block specific URLs. Inject delays to simulate slow networks. Record specific API calls to a database. The API exposes the full request/response lifecycle with hooks for every stage.
Request Replay
Select any captured request and replay it — either as-is or with modifications. Change a parameter, modify a header, alter the request body, and send it again. This is invaluable for testing API endpoints: capture a valid request, then replay it with invalid data to test error handling, with missing auth tokens to test security, or with edge-case values to test validation.
Flow Filtering and Search
Filter captured flows using a powerful filter expression language. Filter by URL pattern (`~u /api/`), by method (`~m POST`), by response code (`~c 500`), by content type (`~t json`), or by body content (`~b error`). Combine filters with AND/OR logic. This lets you focus on the specific traffic you care about in a stream of hundreds of requests.
Map Local / Map Remote
Map Remote redirects requests from one URL to another — useful for pointing an API call at a local server instead of production, or replacing a CDN resource with a local file. Map Local serves responses from local files instead of making upstream requests. Both features let you test how your application behaves with different API responses without modifying the application code.
Who Should Use mitmproxy?
1The Mobile App Developer
Debugging an iOS app that makes API calls to a backend server, this developer configures their iPhone to use mitmproxy as its HTTP proxy and installs the mitmproxy CA certificate. Now every API call the app makes is visible in mitmweb's browser interface. They can see the exact JSON payloads, inspect authentication headers, and identify why the app receives unexpected data. When they find a bug, they replay the problematic request with modifications to test the fix without rebuilding the app.
2The Security Researcher
Auditing a web application for security vulnerabilities, this researcher uses mitmproxy to intercept all traffic between their browser and the application. They inspect session tokens, test for insecure cookie flags, replay authenticated requests to test for CSRF vulnerabilities, and modify request parameters to test for injection attacks. The Python scripting API lets them automate repetitive tests across hundreds of endpoints.
3The API Integration Developer
Integrating with a third-party API that has poor documentation, this developer points their application's traffic through mitmproxy to see exactly what requests the official SDK is making. They reverse-engineer the API by capturing the request/response pairs, documenting the actual payload structure, and identifying undocumented parameters. When the SDK's behavior is unclear, mitmproxy shows the truth.
How to Install mitmproxy on Mac
mitmproxy is available as a Homebrew formula. It's a Python application distributed as a self-contained binary.
Install via Homebrew
Run `brew install mitmproxy`. This installs all three tools: mitmproxy (TUI), mitmweb (web GUI), and mitmdump (CLI).
Start the Proxy
Run `mitmproxy` for the TUI or `mitmweb` for the browser interface. By default, the proxy listens on port 8080.
Configure Your Client
Set your browser or system proxy to `localhost:8080`. For macOS system-wide: System Settings > Network > Wi-Fi > Details > Proxies > Web Proxy (HTTP) and Secure Web Proxy (HTTPS), both pointing to 127.0.0.1:8080.
Install the CA Certificate
With the proxy running, visit http://mitm.it in your browser. Download the macOS certificate and install it in Keychain Access. Set it to 'Always Trust' in the certificate details. This enables HTTPS interception.
Pro Tips
- • For mobile device debugging, connect your phone to the same Wi-Fi network, set the proxy to your Mac's IP address:8080, and install the CA cert from http://mitm.it on the device.
- • Use `mitmproxy --mode reverse:https://api.example.com/` to run mitmproxy as a reverse proxy for a specific server — useful for API debugging without changing client configuration.
- • Save captured flows with `mitmdump -w flows.mitm` and reload them later with `mitmproxy -r flows.mitm` for offline analysis.
Configuration Tips
Use Scripts for Automated API Mocking
Create a Python script (e.g., `mock.py`) that intercepts specific API responses and replaces them with local data. Run it with `mitmproxy -s mock.py`. This is perfect for frontend development — mock backend responses without running a backend, test error states without triggering real errors, and simulate slow responses by adding `time.sleep()` in the script.
Set Up Browser-Only Proxying
Instead of proxying all system traffic, use a browser extension like FoxyProxy (Firefox) or SwitchyOmega (Chrome) to proxy only browser traffic through mitmproxy. This keeps your system traffic unaffected and reduces noise in the captured flows.
Alternatives to mitmproxy
mitmproxy competes with both commercial and open-source proxy tools on macOS.
Proxyman
Proxyman is a native macOS HTTPS proxy with a beautiful, Apple-design-inspired GUI. Certificate installation is automatic, the interface is intuitive, and it supports Apple Silicon natively. It's easier to use than mitmproxy for visual inspection. But Proxyman's free tier has limitations (3 domains), the full version costs $69+, and it can't match mitmproxy's Python scripting capabilities. If you need pretty + easy, choose Proxyman. If you need scriptable + free, choose mitmproxy.
Charles Proxy
Charles Proxy is the long-time incumbent — a Java-based proxy that's been around since 2003. It has a mature GUI with breakpoints, throttling, and SSL proxying. But it costs $50, is Java-based (slow, non-native), and its scripting is limited compared to mitmproxy's Python API. Charles was the default recommendation for years; in 2026, Proxyman and mitmproxy have largely superseded it.
Bruno
Bruno is an API client, not a proxy. It sends requests you define; mitmproxy intercepts requests made by other applications. They're complementary: use Bruno for designing and testing API calls, and mitmproxy for debugging what your application actually sends. If you're confused about why your app's API calls fail, mitmproxy shows you exactly what's going over the wire.
Pricing
mitmproxy is completely free and open source under the MIT License. There are no paid tiers, no premium features, and no usage limits. Development is funded by community contributions and corporate sponsors. The project has been maintained since 2010 and is one of the most established open-source proxy tools.
Pros
- ✓Three interfaces: TUI, web GUI, and headless CLI for different workflows
- ✓Python scripting for automated traffic modification and testing
- ✓Powerful flow filtering with a dedicated expression language
- ✓Request replay with modification for API testing
- ✓Map Local and Map Remote for response mocking
- ✓Completely free and open source (MIT License)
- ✓Cross-platform with consistent behavior
- ✓Active development since 2010 with a mature, stable codebase
Cons
- ✗CA certificate installation required for HTTPS interception
- ✗Certificate setup on mobile devices is fiddly (especially iOS)
- ✗TUI has a learning curve (vim-style keybindings)
- ✗No native macOS GUI — web interface or terminal only
- ✗Python scripting API requires Python knowledge
- ✗Does not support HTTP/3 (QUIC) interception yet
Community & Support
mitmproxy has a large, established community. The GitHub repository (github.com/mitmproxy/mitmproxy) has over 37,000 stars, making it one of the most popular security tools on GitHub. Documentation at docs.mitmproxy.org is thorough, covering installation, certificate setup, scripting, and advanced use cases. The project has been maintained since 2010, primarily by Aldo Cortesi and Maximilian Hils, with hundreds of community contributors. Support happens through GitHub Discussions, and there's an active community on Twitter/X.
Frequently Asked Questions about mitmproxy
Our Verdict
mitmproxy is the most powerful free HTTP/HTTPS proxy available. The Python scripting API sets it apart from every competitor — the ability to programmatically intercept and modify traffic enables testing and debugging workflows that GUI-only tools can't match. The learning curve is real (especially for the TUI and certificate setup), but once you've spent an hour with it, mitmproxy becomes a permanent part of your toolkit. If you debug APIs, develop mobile apps, or do any kind of security testing, install it.
About the Author
Related Technologies & Concepts
Related Topics
Sources & References
Fact-CheckedLast verified: Feb 23, 2026
- 1mitmproxy Official Website
Accessed Feb 23, 2026
Research queries: mitmproxy Mac 2026 HTTPS proxy debugging