内容
# ProxyPin MCP (Android)
English | [中文](README_CN.md)
> **This repo is an MCP-enhanced, Android-only fork of [ProxyPin](https://github.com/wanghongenpin/proxypin)** (synced with upstream **v1.3.0**).
> It ships a built-in **MCP Server (Model Context Protocol)** on top of the full original capture feature set, letting AI clients (Claude, Cursor, Windsurf, etc.) connect directly to the running proxy on your Android device, read capture data, and actively control interception and modification — no extra service or Python script needed.
---
## Features
- **HTTP/HTTPS capture**: full packet capture and HTTPS decryption on Android (VPN-based, no system proxy needed)
- **Built-in MCP Server**: AI can see, analyze, modify and release your traffic in real time
- **QR code device pairing**: connect other phones without manual Wi-Fi proxy config
- **Domain filtering**: intercept only the traffic you need
- **Request search**: keyword, content-type, multi-condition search
- **JavaScript scripts**: dynamic request/response manipulation
- **Request rewrite**: redirect, replace body, modify headers/params
- **Request mapping**: respond with local files/scripts instead of remote server
- **Request decryption**: AES key auto-decrypts message bodies
- **Request blocking**: block requests by URL pattern
- **Breakpoint interception**: Fiddler-style breakpoints, controllable by AI
- **History**: auto-save capture data; HAR import/export
---
## MCP Server
> **TL;DR**: Open ProxyPin, and AI can see every request you capture, help you analyze it, modify it, and release it — like Fiddler breakpoints, but controlled by AI.
### Connection
The MCP Server listens on port **9010** by default and speaks two transports:
- **Streamable HTTP** at `/mcp` — the current MCP transport (protocol `2025-06-18`, with version negotiation and `Mcp-Session-Id` session management). **Recommended.**
- **Legacy HTTP+SSE** at `/sse` — kept for older clients (protocol `2024-11-05`).
The server **starts automatically** when the app launches (default on; toggle in Toolbox → MCP Server).
The port is configurable there as well and is persisted across restarts.
Configure in Claude Desktop / Cursor / Windsurf:
```json
{
"mcpServers": {
"proxypin": {
"url": "http://127.0.0.1:9010/mcp"
}
}
}
```
> Running on a phone? Use the device IP (e.g. `http://192.168.1.5:9010/mcp`) or `adb forward tcp:9010 tcp:9010`.
---
### Available MCP Tools (25 total)
#### 1. Basic Capture Query (9 tools)
| Tool | Description |
|------|-------------|
| `get_request_list` | List captured requests with filters: domain, method, status code, keyword, pagination |
| `get_request_detail` | Full details of a single request: headers, body, response, timing |
| `get_request_body` | Fetch large request/response body content directly |
| `get_request_stats` | Summary stats: domain distribution, status codes, methods, avg latency |
| `search_requests` | Advanced search: URL/Body/Header keyword + time range |
| `get_domain_summary` | Group by domain: unique paths, method distribution, avg latency |
| `get_cookie_info` | Extract Cookie/Set-Cookie headers and analyze attributes |
| `compare_requests` | Diff two requests: URL, Headers, Query params, Body, Status code |
| `analyze_encrypted_content` | Detect Base64/Hex/URL-encoded/JWT content, compute entropy, hint at algorithm |
#### 2. Replay & Code Generation (2 tools)
| Tool | Description |
|------|-------------|
| `replay_request` | Replay a captured request with optional header/body overrides; returns the live response |
| `generate_code` | Convert a captured request to runnable code: Python / JavaScript / cURL / Go |
#### 3. Breakpoint Interception · Modify & Release (5 tools, highlight)
> Fiddler-style breakpoints, but controlled by AI conversation.
| Tool | Description |
|------|-------------|
| `add_breakpoint` | Add a breakpoint rule (URL regex + HTTP method + request/response phase) |
| `list_breakpoints` | List all rules and their enabled state |
| `remove_breakpoint` | Remove a rule by index |
| `get_pending_intercepts` | View all currently paused requests/responses with full data |
| `release_intercept` | Release an intercept with optional modifications: Headers, Body, StatusCode, or abort |
**Typical workflow:**
```
AI → add_breakpoint url=".*api/login.*"
Trigger login in the App
AI → get_pending_intercepts ← reads the full intercepted request
AI → release_intercept requestId=xxx body='{"user":"admin","pass":"test"}'
The modified request is forwarded to the server
```
#### 4. Rewrite Rule Management (3 tools)
| Tool | Description |
|------|-------------|
| `list_rewrite_rules` | List all persistent rewrite rules |
| `add_rewrite_rule` | Add a rule: replace body/headers, update params, redirect (5 types) |
| `remove_rewrite_rule` | Remove a rule by index |
#### 5. JS Script Management (3 tools)
| Tool | Description |
|------|-------------|
| `list_scripts` | List all JS intercept scripts |
| `get_script_content` | Read script source code |
| `create_or_update_script` | AI writes/updates a JS script with `onRequest`/`onResponse`; takes effect immediately |
#### 6. Security Analysis (3 tools)
| Tool | Description |
|------|-------------|
| `find_sensitive_data` | Scan for phone numbers, ID cards, emails, JWT, Bearer tokens, API keys, passwords, private IPs |
| `analyze_auth` | Extract Auth headers, API key headers, Cookie session tokens; auto-decode JWT payloads |
| `extract_api_endpoints` | Group and normalize API paths (replace IDs/UUIDs with placeholders), count calls and status codes |
---
## Download & Build
### Download
Get the latest APK from [GitHub Releases](https://github.com/Mohen0/proxypin-mcp-android/releases)
(`proxypin-mcp-android-{ver}.apk`, universal: arm64-v8a / armeabi-v7a / x86_64).
Repo: [Mohen0/proxypin-mcp-android](https://github.com/Mohen0/proxypin-mcp-android)
### GitHub Actions (recommended)
Push a `v*` tag and the CI builds a universal release APK and attaches it to a GitHub Release:
```bash
git tag v1.3.0-mcp
git push origin v1.3.0-mcp
# GitHub Actions builds proxypin-mcp-android-{ver}.apk automatically
```
Workflow: `.github/workflows/release.yml` (Android only).
### Android Signing (optional)
Set these Secrets in GitHub → Settings → Secrets → Actions to enable release signing:
| Secret | Description |
|--------|-------------|
| `ANDROID_KEYSTORE_BASE64` | Output of `base64 -w 0 your.keystore` |
| `ANDROID_STORE_PASSWORD` | storePassword |
| `ANDROID_KEY_ALIAS` | keyAlias |
| `ANDROID_KEY_PASSWORD` | keyPassword |
Without these secrets, the build automatically falls back to debug signing (sideloadable, not Play Store ready).
### Local build
Requirements: Flutter **3.44.8+** (Dart ≥ 3.12.2), Android SDK, Java 17.
```bash
flutter pub get
flutter gen-l10n
flutter build apk --release # universal APK
# output: build/app/outputs/flutter-apk/app-release.apk
```
---
## Project layout
```
android/ Android runner (VPN, PiP, installed apps, process info plugins)
lib/
main.dart App entry (Android)
network/ Proxy core: capture, TLS MITM, interceptors
mcp/ MCP Server + tools
ui/mobile/ Android UI
storage/ History / favorites persistence
assets/ CA cert, icons, JS built-ins
```
---
## Staying in sync with upstream
```bash
git fetch upstream
git merge upstream/main
git push origin mcp-main
```
---
## Upstream
Original ProxyPin: [https://github.com/wanghongenpin/proxypin](https://github.com/wanghongenpin/proxypin)
Thanks to [@wanghongenpin](https://github.com/wanghongenpin) for the excellent original work.
---
## License
Apache License 2.0, same as the upstream project.
<img alt="image" width="580px" height="420px" src="https://github.com/user-attachments/assets/6c1345ab-c95c-415d-ac59-470c764b59a2">.<img alt="image" height="500px" src="https://github.com/user-attachments/assets/3c5572b0-a9e5-497c-8b42-f935e836c164">
### Powered by
[](https://jb.gg/OpenSource)
连接信息
猜你喜欢
暂无推荐服务器