Content
# Android Proxy MCP
Android packet capture service based on MCP (Model Context Protocol), allowing AI assistants to help you capture and analyze HTTP/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 Powered**: Let Claude help you analyze network requests through natural language
## Architecture
```
┌─────────────────┐ SQLite ┌─────────────────┐
│ Proxy Service │ ─────────────→ │ MCP Server │
│ (Manual Launch) │ Traffic Data Sharing │ (Claude Call) │
│ mitmdump │ │ Query/Search/Analysis │
└─────────────────┘ └─────────────────┘
↑
│ HTTP/HTTPS
│
┌─────────┐
│ Phone │
└─────────┘
```
## Quick Start
### 1. Environment Requirements
- Python 3.11+
- [uv](https://github.com/astral-sh/uv) (Python Package Manager)
**Install uv:**
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or via pip
pip install uv
```
### 2. Installation
```bash
# Clone the project
git clone https://github.com/yourname/android-proxy-mcp.git
cd android-proxy-mcp
# Install dependencies
uv sync
```
### 3. Configure Claude Desktop
Edit the Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"android-proxy": {
"command": "uv",
"args": ["--directory", "/path/to/android-proxy-mcp", "run", "android-proxy-mcp"]
}
}
}
```
> Replace `/path/to/android-proxy-mcp` with the actual project path
### 4. Restart Claude Desktop
After configuration, restart Claude Desktop for the configuration to take effect.
---
## Usage
### Step 1: Start the Proxy
**Run in the terminal:**
```bash
uv run android-proxy-start
```
You will see the following output:
```
╔════════════════════════════════════════════════════════════╗
║ 🚀 Android Proxy MCP Startup Guide ║
╚════════════════════════════════════════════════════════════╝
════════════════════════════════════════════════════════════
Environment Check
════════════════════════════════════════════════════════════
✓ Port 8288 is available
════════════════════════════════════════════════════════════
Phone Configuration
════════════════════════════════════════════════════════════
Phone Wi-Fi proxy settings:
┌─────────────────────────────────┐
│ Server: 192.168.1.100 │
│ Port: 8288 │
└─────────────────────────────────┘
Certificate Installation: Visit http://mitm.it in your phone's browser
════════════════════════════════════════════════════════════
Starting Proxy (Ctrl+C to stop)
════════════════════════════════════════════════════════════
```
> Keep this terminal window running, do not close it.
### Step 2: Configure Phone Proxy
**Make sure your phone and computer are on the same Wi-Fi network.**
1. On your phone, go to **Settings → Wi-Fi**
2. Long press the currently connected Wi-Fi → **Modify network**
3. Expand **Advanced options**
4. Set the proxy settings to **Manual**
5. Fill in the IP and port displayed by the startup script
6. Save
### Step 3: Install CA Certificate (Required for HTTPS)
1. Visit `http://mitm.it` in your phone's browser (via proxy)
2. Select the Android icon to download the certificate
3. Settings → Security → Encryption & credentials → Install a certificate → CA certificate
4. Select the downloaded certificate file to install
> ⚠️ **Note**: Android 7+ user certificates are not trusted by Apps by default, and can only capture HTTPS traffic from browsers and some applications.
#### Install System Certificate (Root Users)
If your device is rooted (Magisk installed), you can move the user certificate to a system certificate:
1. First install the user certificate as described above
2. Install the `resources/MoveCertificate-v1.5.5.zip` Magisk module:
- Open Magisk → Modules → Install from local
- Select `resources/MoveCertificate-v1.5.5.zip` in the project
- Reboot the device
3. After rebooting, the user certificate will be automatically moved to the system certificate directory
---
### Step 4: Query Traffic in Claude
Open **Claude Desktop** and query traffic using natural language:
**Basic Queries:**
> "Show recent network requests"
> "Show requests for api.example.com"
> "Show all failed requests (status code 4xx or 5xx)"
**Search Content:**
> "Search for requests containing 'John Doe' in the response"
> "Search for requests containing search in the URL"
> "Search for requests containing X-Token in the request header"
**View Large Responses:**
> "Read the response body of req-5"
> "Continue reading the req-5 response body, starting from 4000"
**Intelligent Analysis:**
> "Help me find the search API for the CoolApk app"
> "Analyze the request parameters of this API"
### Step 5: Stop Packet Capture
Press `Ctrl+C` in the terminal window running the proxy to stop the proxy.
Remember to turn off the proxy in your phone's Wi-Fi settings.
---
## MCP Tool List
| Tool | Description |
|-----|------|
| `proxy_status` | Get proxy status |
| `traffic_list` | List traffic (supports domain/status code/type filtering) |
| `traffic_search` | Search traffic content (URL/request header/request body/response header/response body) |
| `traffic_get_detail` | Get request metadata (request headers, response headers, etc.) |
| `traffic_read_body` | Chunk read large response body |
| `traffic_clear` | Clear traffic records |
| `get_cert_info` | Get certificate installation guide |
---
## FAQ
### Q: Cannot access the internet after configuring the phone proxy?
1. Make sure your computer and phone are on the same Wi-Fi
2. Make sure the proxy is started (check the terminal window)
3. Check if your computer's firewall allows port 8288
4. Try using the computer's IP (not localhost)
### Q: Can capture HTTP but not HTTPS?
You need to install the CA certificate. Visit `http://mitm.it` in your phone's browser to download and install it.
### Q: Installed the certificate but some Apps still cannot capture HTTPS?
- Android 7+ user certificates are not trusted by Apps by default → Need to install a system certificate (see above)
- Some Apps have SSL Pinning (certificate pinning) → See bypass solution below
### Q: How to bypass SSL Pinning?
It is recommended to use **LSPosed + Disable SSL Verification Plugin**:
1. Install [Magisk](https://github.com/topjohnwu/Magisk) (requires Root)
2. Install the [LSPosed](https://github.com/LSPosed/LSPosed) module
3. Install any of the following plugins:
- [TrustMeAlready](https://github.com/ViRb3/TrustMeAlready)
- [JustTrustMe](https://github.com/Fuzion24/JustTrustMe)
4. Enable the plugin in LSPosed and check the target App
5. Restart the target App
### Q: The response is too large, MCP cannot return it?
Use `traffic_search` to search for keywords to locate, and then use `traffic_read_body` to read in chunks.
---
## Project Structure
```
android-proxy-mcp/
├── README.md
├── pyproject.toml
├── src/
│ └── android_proxy_mcp/
│ ├── cli/ # Command-line tools
│ │ └── start.py # Proxy startup script
│ ├── core/ # Core modules
│ │ └── sqlite_store.py # SQLite traffic storage
│ ├── tools/ # MCP Tools
│ └── server.py # MCP Server entry point
├── tests/
├── docs/ # Documentation
└── resources/ # Resource files
└── MoveCertificate-v1.5.5.zip # Certificate moving module
```
## Development
```bash
# Install development dependencies
uv sync --extra dev
# Run tests
uv run pytest tests/ -v
# Code formatting
uv run ruff format .
```
## License
MIT License
