Content
# MITM Proxy MCP
A proxy-based packet capture service using MCP (Model Context Protocol iOS simulators, allowing AI assistants to help with capturing and/HTTPS traffic.
## Features
- **Packet Capture**: Capture HTTP/HTTPS traffic, supporting filtering by domain, status code, and resource type
- **Intelligent Search**: Search request/response content, supporting large response chunk reading
- **AI-Driven**: Use natural language to let AI assistants analyze network requests
## Architecture
```
┌ SQLite ─────────────────┐
│ Proxy Service │────→ │ MCP Service │
│ (Manual start) │ Traffic data sharing │ (Cursor calls) │
│ mitmdump │ │ Query/Search/Analyze │
└─────────────────┘ └─────────────────┘
↑
│ HTTP/HTTPS
│
┌─────────────┐
│ iOS Simulator │
└────────────```
## Quick Start
### 1. Environment Requirements
3.11+
- [uv](https://github.com/astral-sh/uv) (Python package manager)
**Install uv:**
```bash
# macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or via pip
pip install uv
```
### 2. Installation
```bash
# Download project
cd mitmproxy-mcp
# Install dependencies
uv sync
```
### 3. One-Click Installation (Recommended)
**Remote installation (no manual clone required):**
```bash
curl -fsSL https://raw.githubusercontent.com/Aillumine/mitmproxy-mcp/main/install.sh | bash
```
Automatically completes: clones to `~/.mitmproxy-mcp`, installs dependencies, configures MCP, installs user-level Skill, supporting Cursor, Claude Code, and Antigravity.
**Local installation (if repository already cloned):**
```bash
bash install-skill.sh
```
### 4. Manual MCP Configuration
Write the following content to the corresponding IDE configuration file, replacing `/path/mitmproxy-mcp` with the actual project path.
**Cursor** — `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"user-mitmproxy": {
"command": "uv",
"args": ["", "/path/mitmproxy-mcp", "run", "mitmproxy-mcp"]
}
}
}
```
**Claude — `~/.claude.json`
```json
{
"mcpServers": {
"user-mitmproxy": {
"command": "uv",
"args": ["--directory", "/path/mitmproxy-mcp", "run", "proxy-mcp"]
}
}
}
```
**Antigravity** — `~/.gemini/antigravity/mcp_config.json`
```json
{
"mcpServers": {
"user-mitmproxy": {
"command": "uv",
"args": ["--directory", "/path/mitmproxy-mcp", "run", "mitmproxy-mcp"]
}
```
### 5. Restart IDE
After configuration, restart the corresponding IDE to make the configuration take effect.
## Usage
### Step 1: Start Proxy
There are three startup methods:
**Method 1: Global alias (recommended, automatically configured after installation)**
```bash
proxy
```
The installation script will automatically add the `proxy` alias to `~/.zshrc`, making it available in new terminal windows. Equivalent to Method 2.
**Method 2: Start proxy + automatically set Mac system proxy**
```bash
uv run mitmproxy-start --setup-proxy
```
This command will automatically set the Mac Wi-Fi's HTTP/HTTPS proxy to `127.0.0.1:8888`, and restore it when closed+C).
**Method Start proxy only (manual configuration)**
```bash
uvmproxy-start
configuration of the system proxy on Mac, see " Configuration" below.
> terminal window running, do.
### Step 2: Configure iOS Simulator Proxy
iOS simulator will automatically Mac's system proxy settings `--setup-proxy` is the proxy is already configured, Step 3.
<summary><strong>Manual Proxystrong> ( using --setup-proxy)</summary>
1. Mac System Settings → Network → Wi-Fi → Advanced2. Check ** (HTTP)**: `127.0.0.1:8888`
3. Check **Secure Web Proxy (HTTPS)**: `127.0.0.1:8888`
4. Save
</details>
### Step 3: Install CA Certificate (required for HTTPS capture)
**iOS Simulator Certificate Installation:**
1. In the iOS simulator's Safari, access `http://mitm.it`
2. Click the **Apple** icon to download the certificate
3. Settings → General → VPN & Device Management → Install Profile
4. Settings → General → About → Certificate Trust Settings → Enable mitmproxy
**Mac Browser Certificate Installation (important!):**
If the Mac system proxy is enabled, Mac browsers also need to install the certificate to access HTTPS otherwise, certificate errors will occur.
1. In the Mac browser (Safari/Chrome), access `http://mitm.it`
2. Click the **Apple** icon to download the certificate (`mitmproxy-ca-cert.pem`)
3. Double-click the downloaded certificate file to open "Keychain Access"
4. Find the `mitmproxy` certificate, double-click to open
5. Expand the "Trust" option, set "Use this certificate" to "Always Trust"
6. Close the window, input the password to confirm
> **Tip**: After installing the certificate, Mac browsers can normally access HTTPS websites. If browsers still cannot open web pages, check if the proxy is normally started.
### Step 4: Query Traffic in Cursor
In **Cursor**, use natural language to query traffic:
**Basic Query:**
> "Show recent network requests"
> requests to /apim/v3/earn/"
> all failed requests (status code 4xx or 5xx)"
**Search Content:**
> requests with '收益先锋-BTC' in the response"
> "Search requests with 'search' in the URL"
> "Search requests with 'X-Token' in the request header"
**View Large Response:**
Read the response body of5"
> "Continue response body of req- starting from 4000Intelligent Analysis:**
Help me find the holdings"
> "Analyze the this API"
5: Stop PacketIn the terminal window where is running, press `` to stop the proxy If `--setup-proxy used, the Mac system be automatically closed.
- proxy is manually configured close it in the settings.
## Tool List Tool | Description |
|-----|------|
| `proxy_start` | **Start Proxy Service** (run in the background, terminal operation required) |
proxy_stop` | Service** |
| `` | Get proxy status |
| `traffic_list` | List traffic (supporting domain/status code/type filtering) |
| `traffic_search` | Search traffic content (URL/request header/response header/response body) `traffic_get_detail Get request metadata (request response header, etc.) |
traffic_read_body` | Read large response bodies in chunks |
| `traffic_clear` | Clear traffic records |
| `get_cert_info` | Get certificate installation guide |
### Quick Start Proxy
Now you can directly start the proxy in Cursor without manual terminal operations:
> "Start proxy"
> "Start proxy and set Mac system proxy"
> "Stop proxy"
Cursor will automatically call `proxy_start` and `proxy_stop` tools to manage the proxy service.
## Frequently Asked Questions
### Q: iOS simulator configuration proxy failed to connect to?
1. Confirm the proxy is started (check the terminal window)
2. Confirm the Mac system proxy settings are correct (127.0.0.1:8888)
3. Check if the proxy is listening on 0.0.0.0 (not just localhost)
4. Confirm the mitmproxy CA certificate is installed and trusted
### Q: Can capture HTTP HTTPS?
The CA to be installed in the simulator. Access `http://mitm.it` in Safari to download and install, and the certificate trust settings.
### Q: Installed certificate requests still fail?
- Confirm the certificate is enabled in Trust Settings"
- may have SSL Pinning
### Q: Mac browser cannot access web opening proxy?
**Possible reasons:**
1. **CA certificate not installed** (most common)
- Mac browsers need to install the mitmproxy CA certificate to access HTTPS websites
- Access `http://mitm.it` in the browser to download and install the certificate to Keychain
- Set the certificate to "Always Trust"
2. **Proxy not started correctly - Check if the proxy process is running: `li :8888`
- Check proxy logs for - Try manually running run mitmproxy-start` in the terminal to view error messages
3. **Port occupied**
- Check if the port is occupied by other processes: `lsof -i :8888`
- Use `proxy_stop` to stop the old proxy, or use `--port` to specify another port
4. **System proxy settings incorrect**
- Confirm the proxy address is `127.0.0.1:8888` (not other IP)
- Confirm both HTTP and HTTPS proxies are enabled
### Response too large, MCP?
Use `traffic to search for keywords, `traffic_read_body` to read in chunks.
## Project Structure
```
mitmproxy-mcp/
├── README.md
├── pyproject.toml
├── src/
│ └── mitm_proxy_mcp/
│ cli/ # Command-line tools
│ │ └── start.py # Proxy
│ ├── core/ # Core modules
│ │ └── sqlite_store.py # SQLite traffic storage
│ ├── tools/ # MCP tools
│ └── server.py # MCP service entry
├── tests/
├── docs/ # Documentation
└── resources/ # Resource files
└── MoveCertificate-v1.5.5.zip # Certificate movement module
```
## Development
```bash
# Install development dependencies
uv sync --extra dev
# Run tests
uv run pytest testsv
# Code formatting
uv run ruff format .
```
