Android Proxy MCP

🚀 Android Proxy MCP

基於 MCP (Model Context Protocol) 的 Android 抓包服務，讓 AI 助手能夠幫你抓取和分析 HTTP/HTTPS 流量。

🚀 快速開始

環境要求

• Python 3.11+
• uv (Python 包管理器)

安裝 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"

# 或通過 pip
pip install uv

安裝

# 克隆項目
git clone https://github.com/yourname/android-proxy-mcp.git
cd android-proxy-mcp

# 安裝依賴
uv sync

配置 Claude Desktop

編輯 Claude Desktop 配置文件： 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"]
    }
  }
}

將 /path/to/android-proxy-mcp 替換為實際項目路徑

重啟 Claude Desktop

配置完成後，重啟 Claude Desktop 使配置生效。

✨ 主要特性

• 抓包：捕獲 HTTP/HTTPS 流量，支持按域名、狀態碼、資源類型篩選。
• 智能搜索：搜索請求/響應內容，支持大響應分片讀取。
• AI 驅動：通過自然語言讓 Claude 幫你分析網絡請求。

📦 安裝指南

環境要求

• Python 3.11+
• uv (Python 包管理器)

安裝 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"

# 或通過 pip
pip install uv

安裝

# 克隆項目
git clone https://github.com/yourname/android-proxy-mcp.git
cd android-proxy-mcp

# 安裝依賴
uv sync

配置 Claude Desktop

編輯 Claude Desktop 配置文件： 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"]
    }
  }
}

將 /path/to/android-proxy-mcp 替換為實際項目路徑

重啟 Claude Desktop

配置完成後，重啟 Claude Desktop 使配置生效。

💻 使用示例

第一步：啟動代理

在終端中運行：

uv run android-proxy-start

你會看到如下輸出：

╔════════════════════════════════════════════════════════════╗
║            🚀 Android Proxy MCP 啟動向導                   ║
╚════════════════════════════════════════════════════════════╝

════════════════════════════════════════════════════════════
  環境檢測
════════════════════════════════════════════════════════════

    ✓ 端口 8288 可用

════════════════════════════════════════════════════════════
  手機配置
════════════════════════════════════════════════════════════

    手機 Wi-Fi 代理設置:

       ┌─────────────────────────────────┐
       │  服務器:    192.168.1.100       │
       │  端  口:        8288            │
       └─────────────────────────────────┘

    證書安裝: 手機瀏覽器訪問 http://mitm.it

════════════════════════════════════════════════════════════
  啟動代理 (Ctrl+C 停止)
════════════════════════════════════════════════════════════

保持這個終端窗口運行，不要關閉。

第二步：配置手機代理

確保手機和電腦在同一 Wi-Fi 網絡下。

1. 手機進入 設置 → Wi-Fi。
2. 長按當前連接的 Wi-Fi → 修改網絡。
3. 展開 高級選項。
4. 代理設置選擇 手動。
5. 填寫啟動腳本顯示的 IP 和端口。
6. 保存。

第三步：安裝 CA 證書（抓 HTTPS 必須）

1. 手機瀏覽器訪問 http://mitm.it（通過代理訪問）。
2. 選擇 Android 圖標下載證書。
3. 設置 → 安全 → 加密與憑據 → 安裝證書 → CA 證書。
4. 選擇下載的證書文件安裝。

⚠️ 注意：Android 7+ 用戶證書默認不被 App 信任，只能抓取瀏覽器和部分應用的 HTTPS 流量。

安裝系統證書（Root 用戶）

如果你的設備已 Root（安裝了 Magisk），可以將用戶證書移動為系統證書：

1. 先按照上述步驟安裝用戶證書。
2. 安裝 resources/MoveCertificate-v1.5.5.zip Magisk 模塊：
   • 打開 Magisk → 模塊 → 從本地安裝。
   • 選擇項目中的 resources/MoveCertificate-v1.5.5.zip。
   • 重啟設備。
3. 重啟後，用戶證書會自動移動到系統證書目錄。

第四步：在 Claude 中查詢流量

打開 Claude Desktop，用自然語言查詢流量： 基礎查詢：

"顯示最近的網絡請求" "顯示 api.example.com 的請求" "顯示所有失敗的請求（狀態碼 4xx 或 5xx）"

搜索內容：

"搜索響應中包含 '張三' 的請求" "搜索 URL 中包含 search 的請求" "搜索請求頭中包含 X-Token 的請求"

查看大響應：

"讀取 req-5 的響應體" "繼續讀取 req-5 響應體，從 4000 開始"

智能分析：

"幫我找酷安 app 的搜索接口" "分析這個 API 的請求參數"

第五步：停止抓包

在運行代理的終端窗口按 Ctrl+C 停止代理。 記得在手機 Wi-Fi 設置中關閉代理。

📚 詳細文檔

MCP 工具列表

常見問題

Q: 手機配置代理後無法上網？

1. 確認電腦和手機在同一 Wi-Fi。
2. 確認代理已啟動（檢查終端窗口）。
3. 檢查電腦防火牆是否允許 8288 端口。
4. 嘗試用電腦 IP（不是 localhost）。

Q: 能抓到 HTTP 但抓不到 HTTPS？

需要安裝 CA 證書。手機瀏覽器訪問 http://mitm.it 下載安裝。

Q: 安裝了證書但某些 App 還是抓不到 HTTPS？

• Android 7+ 用戶證書默認不被 App 信任 → 需要安裝系統證書（參考上方）。
• 部分 App 有 SSL Pinning（證書鎖定）→ 參考下方繞過方案。

Q: 如何繞過 SSL Pinning？

推薦使用 LSPosed + 禁用 SSL 驗證插件：

1. 安裝 Magisk（需要 Root）。
2. 安裝 LSPosed 模塊。
3. 安裝以下任一插件：
   • TrustMeAlready
   • JustTrustMe
4. 在 LSPosed 中啟用插件，勾選目標 App。
5. 重啟目標 App。

Q: 響應太大，MCP 無法返回？

使用 traffic_search 搜索關鍵詞定位，然後用 traffic_read_body 分片讀取。

項目結構

android-proxy-mcp/
├── README.md
├── pyproject.toml
├── src/
│   └── android_proxy_mcp/
│       ├── cli/              # 命令行工具
│       │   └── start.py      # 代理啟動腳本
│       ├── core/             # 核心模塊
│       │   └── sqlite_store.py  # SQLite 流量存儲
│       ├── tools/            # MCP 工具
│       └── server.py         # MCP 服務入口
├── tests/
├── docs/                     # 文檔
└── resources/                # 資源文件
    └── MoveCertificate-v1.5.5.zip  # 證書移動模塊

開發

# 安裝開發依賴
uv sync --extra dev

# 運行測試
uv run pytest tests/ -v

# 代碼格式化
uv run ruff format .

🔧 技術細節

┌─────────────────┐     SQLite      ┌─────────────────┐
│  代理服務        │ ─────────────→  │  MCP 服務        │
│  (終端手動啟動)   │   流量數據共享   │  (Claude 調用)   │
│  mitmdump       │                 │  查詢/搜索/分析   │
└─────────────────┘                 └─────────────────┘
        ↑
        │ HTTP/HTTPS
        │
   ┌─────────┐
   │  手機    │
   └─────────┘

📄 許可證

MIT License