Android Proxy MCP

🚀 Android Proxy MCP

MCP (Model Context Protocol) ベースの Android パケットキャプチャサービスで、AI アシスタントを使って HTTP/HTTPS トラフィックのキャプチャと分析ができます。

🚀 クイックスタート

1. 環境要件

• 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

2. インストール

# プロジェクトをクローン
git clone https://github.com/yourname/android-proxy-mcp.git
cd android-proxy-mcp

# 依存関係をインストール
uv sync

3. 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 を実際のプロジェクトパスに置き換えてください。

4. Claude Desktop の再起動

設定が完了したら、Claude Desktop を再起動して設定を有効にします。

✨ 主な機能

• パケットキャプチャ: HTTP/HTTPS トラフィックをキャプチャし、ドメイン名、ステータスコード、リソースタイプでのフィルタリングをサポートします。
• スマート検索: リクエスト/レスポンス内容を検索し、大きなレスポンスの分割読み取りをサポートします。
• AI 駆動: 自然言語で Claude にネットワークリクエストの分析を依頼できます。

🔧 技術詳細

┌─────────────────┐     SQLite      ┌─────────────────┐
│  代理服务        │ ─────────────→  │  MCP 服务        │
│  (终端手动启动)   │   流量数据共享   │  (Claude 调用)   │
│  mitmdump       │                 │  查询/搜索/分析   │
└─────────────────┘                 └─────────────────┘
        ↑
        │ HTTP/HTTPS
        │
   ┌─────────┐
   │  手机    │
   └─────────┘

💻 使用例

基本的な使用法

手順 1: プロキシの起動

ターミナルで実行：

uv run android-proxy-start

以下の出力が表示されます：

╔════════════════════════════════════════════════════════════╗
║            🚀 Android Proxy MCP 启动向导                   ║
╚════════════════════════════════════════════════════════════╝

════════════════════════════════════════════════════════════
  环境检测
════════════════════════════════════════════════════════════

    ✓ 端口 8288 可用

════════════════════════════════════════════════════════════
  手机配置
════════════════════════════════════════════════════════════

    手机 Wi-Fi 代理设置:

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

    证书安装: 手机浏览器访问 http://mitm.it

════════════════════════════════════════════════════════════
  启动代理 (Ctrl+C 停止)
════════════════════════════════════════════════════════════

このターミナルウィンドウを開いたままにしてください。

手順 2: 携帯電話のプロキシ設定

携帯電話とコンピュータが同じ Wi-Fi ネットワークに接続されていることを確認してください。

1. 携帯電話で 設定 → Wi-Fi を開きます。
2. 現在接続している Wi-Fi を長押しし、ネットワークを編集 を選択します。
3. 詳細オプション を展開します。
4. プロキシ設定を 手動 に設定します。
5. 起動スクリプトに表示された IP アドレスとポートを入力します。
6. 設定を保存します。

手順 3: CA 証明書のインストール（HTTPS キャプチャに必須）

1. 携帯電話のブラウザで http://mitm.it にアクセスします（プロキシ経由）。
2. Android アイコンを選択して証明書をダウンロードします。
3. 設定 → セキュリティ → 暗号化と資格情報 → 証明書のインストール → CA 証明書 を選択します。
4. ダウンロードした証明書ファイルを選択してインストールします。

⚠️ 注意: Android 7 以上のユーザーは、証明書がデフォルトでアプリに信頼されないため、ブラウザと一部のアプリの HTTPS トラフィックのみをキャプチャできます。

Root ユーザーの場合のシステム証明書のインストール

デバイスが Root 化されている場合（Magisk がインストールされている場合）、ユーザー証明書をシステム証明書に移動できます。

1. 上記の手順でユーザー証明書をインストールします。
2. resources/MoveCertificate-v1.5.5.zip Magisk モジュールをインストールします。
   • Magisk を開き、モジュール → ローカルからインストール を選択します。
   • プロジェクト内の resources/MoveCertificate-v1.5.5.zip を選択します。
   • デバイスを再起動します。
3. 再起動後、ユーザー証明書が自動的にシステム証明書ディレクトリに移動されます。

手順 4: Claude でトラフィックをクエリする

Claude Desktop を開き、自然言語でトラフィックをクエリします。

基本クエリ：

"最近のネットワークリクエストを表示" "api.example.com のリクエストを表示" "すべての失敗したリクエスト（ステータスコード 4xx または 5xx）を表示"

内容検索：

"レスポンスに '张三' が含まれるリクエストを検索" "URL に search が含まれるリクエストを検索" "リクエストヘッダーに X-Token が含まれるリクエストを検索"

大きなレスポンスの表示：

"req-5 のレスポンスボディを読み取る" "req-5 のレスポンスボディを 4000 から続けて読み取る"

スマート分析：

"酷安 app の検索インターフェイスを見つけてくれ" "この API のリクエストパラメータを分析してくれ"

手順 5: パケットキャプチャの停止

プロキシを実行しているターミナルウィンドウで Ctrl+C を押してプロキシを停止します。 携帯電話の Wi-Fi 設定でプロキシを無効にすることを忘れないでください。

📦 MCP ツールリスト

📚 ドキュメント

Q: 携帯電話でプロキシを設定した後、インターネットに接続できない場合はどうすればいいですか？

1. コンピュータと携帯電話が同じ Wi-Fi に接続されていることを確認します。
2. プロキシが起動していることを確認します（ターミナルウィンドウを確認）。
3. コンピュータのファイアウォールが 8288 ポートを許可していることを確認します。
4. コンピュータの IP アドレス（localhost ではなく）を使用してみてください。

Q: HTTP はキャプチャできるが、HTTPS はキャプチャできない場合はどうすればいいですか？

CA 証明書をインストールする必要があります。携帯電話のブラウザで http://mitm.it にアクセスしてダウンロードし、インストールしてください。

Q: 証明書をインストールしたが、一部のアプリで HTTPS をキャプチャできない場合はどうすればいいですか？

• Android 7 以上のユーザーは、証明書がデフォルトでアプリに信頼されないため、システム証明書をインストールする必要があります（上記を参照）。
• 一部のアプリには SSL Pinning（証明書ロック）がある場合があります → 以下の回避策を参照してください。

Q: SSL Pinning を回避するにはどうすればいいですか？

LSPosed + 禁止 SSL 検証プラグイン の使用をおすすめします。

1. Magisk をインストールします（Root が必要）。
2. LSPosed モジュールをインストールします。
3. 以下のいずれかのプラグインをインストールします。
   • TrustMeAlready
   • JustTrustMe
4. LSPosed でプラグインを有効にし、対象のアプリを選択します。
5. 対象のアプリを再起動します。

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 .

📄 ライセンス

MIT License