Android Proxy MCP

🚀 Android Proxy MCP

An Android packet capture service based on MCP (Model Context Protocol), enabling AI assistants to capture and analyze HTTP/HTTPS traffic.

✨ Features

• Packet Capture: Capture HTTP/HTTPS traffic and support filtering by domain name, status code, and resource type.
• Intelligent Search: Search request/response content and support sharded reading of large responses.
• AI-Driven: Let Claude analyze network requests through natural language.

🔧 Architecture

┌─────────────────┐     SQLite      ┌─────────────────┐
│  Proxy Service   │ ─────────────→  │  MCP Service    │
│  (Manually started on the terminal) │   Traffic data sharing   │  (Invoked by Claude)   │
│  mitmdump       │                 │  Query/Search/Analysis   │
└─────────────────┘                 └─────────────────┘
        ↑
        │ HTTP/HTTPS
        │
   ┌─────────┐
   │  Mobile │
   └─────────┘

🚀 Quick Start

1. Environment Requirements

• Python 3.11+
• uv (Python package manager)

Install uv:

# 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

# 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

{
  "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 the configuration is complete, restart Claude Desktop to make the configuration take effect.

💻 Usage Examples

Step 1: Start the Proxy

Run in the terminal:

uv run android-proxy-start

You will see the following output:

╔════════════════════════════════════════════════════════════╗
║            🚀 Android Proxy MCP Startup Wizard           ║
╚════════════════════════════════════════════════════════════╝

════════════════════════════════════════════════════════════
  Environment Check
════════════════════════════════════════════════════════════

    ✓ Port 8288 is available

════════════════════════════════════════════════════════════
  Mobile Configuration
════════════════════════════════════════════════════════════

    Mobile Wi-Fi proxy settings:

       ┌─────────────────────────────────┐
       │  Server:    192.168.1.100       │
       │  Port:        8288            │
       └─────────────────────────────────┘

    Certificate installation: Visit http://mitm.it on the mobile browser.

════════════════════════════════════════════════════════════
  Start the Proxy (Press Ctrl+C to stop)
════════════════════════════════════════════════════════════

Keep this terminal window running and do not close it.

Step 2: Configure the Mobile Proxy

Ensure that the mobile phone and the computer are on the same Wi-Fi network.

1. Go to Settings → Wi-Fi on the mobile phone.
2. Long-press the currently connected Wi-Fi → Modify Network.
3. Expand Advanced Options.
4. Select Manual for the proxy settings.
5. Fill in the IP and port displayed by the startup script.
6. Save the settings.

Step 3: Install the CA Certificate (Required for HTTPS Capture)

1. Visit http://mitm.it on the mobile browser (through the proxy).
2. Select the Android icon to download the certificate.
3. Go to Settings → Security → Encryption & Credentials → Install Certificate → CA Certificate.
4. Select the downloaded certificate file to install.

⚠️ Important Note: On Android 7+ devices, certificates are not trusted by apps by default, so only HTTPS traffic from browsers and some apps can be captured.

Install the System Certificate (for Rooted Users)

If your device is rooted (with Magisk installed), you can move the user certificate to the system certificate:

1. Install the user certificate according to the above steps.
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.
   • Restart the device.
3. After restarting, the user certificate will be automatically moved to the system certificate directory.

Step 4: Query Traffic in Claude

Open Claude Desktop and query traffic in natural language:

Basic Queries:

"Show recent network requests." "Show requests from api.example.com." "Show all failed requests (status code 4xx or 5xx)."

Search Content:

"Search for requests whose responses contain 'Zhang San'." "Search for requests whose URLs contain 'search'." "Search for requests whose headers contain 'X-Token'."

View Large Responses:

"Read the response body of req-5." "Continue reading the response body of req-5, starting from 4000."

Intelligent Analysis:

"Find the search interface of the Coolapk app for me." "Analyze the request parameters of this API."

Step 5: Stop Packet Capture

Press Ctrl+C in the terminal window where the proxy is running to stop the proxy.

Remember to turn off the proxy in the mobile Wi-Fi settings.

📦 MCP Tool List

❓ Frequently Asked Questions

Q: Unable to access the Internet after configuring the proxy on the mobile phone?

1. Confirm that the computer and the mobile phone are on the same Wi-Fi.
2. Confirm that the proxy has been started (check the terminal window).
3. Check if the computer firewall allows port 8288.
4. Try using the computer's IP address (not localhost).

Q: Can capture HTTP but not HTTPS?

You need to install the CA certificate. Visit http://mitm.it on the mobile browser to download and install it.

Q: Installed the certificate but still cannot capture HTTPS traffic for some apps?

• On Android 7+ devices, certificates are not trusted by apps by default → You need to install the system certificate (refer to the above section).
• Some apps have SSL Pinning (certificate locking) → Refer to the bypass solution below.

Q: How to bypass SSL Pinning?

It is recommended to use LSPosed + Disable SSL Verification Plugin:

1. Install Magisk (requires Root).
2. Install the LSPosed module.
3. Install one of the following plugins:
   • TrustMeAlready
   • JustTrustMe
4. Enable the plugin in LSPosed and select the target app.
5. Restart the target app.

Q: The response is too large and MCP cannot return it?

Use traffic_search to search for keywords and locate the response, then use traffic_read_body to read it in shards.

📁 Project Structure

android-proxy-mcp/
├── README.md
├── pyproject.toml
├── src/
│   └── android_proxy_mcp/
│       ├── cli/              # Command-line tools
│       │   └── start.py      # Proxy startup script
│       ├── core/             # Core module
│       │   └── 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

# Install development dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Code formatting
uv run ruff format .

📄 License

MIT License