# APK-MCP — Windows-First APK Reverse Engineering MCP Server

![APK-MCP Architecture](docs/architecture.png)

**APK-MCP** provides AI agents (Claude Desktop, Cursor, VSCode MCP extensions, etc.) with a unified Model Context Protocol (MCP) interface for Android APK reverse engineering, metadata analysis, Smali/resource editing, rebuilding, alignment, signing, verification, and ADB device testing.

No manual launching of JADX, Apktool, APKEditor, ADB, or signing utilities is required.

---

## Quick Start (Windows One-Command Setup)

```powershell
git clone https://github.com/tkb-bit/APK-MCP.git
cd APK-MCP
.\install.ps1
```

Or using the CLI launcher:

```powershell
.\apk-mcp.ps1 setup
```

---

## 🤖 AI Agent Master Prompt (Copy & Paste to your AI Client)

Paste this prompt to your AI Client (Claude, Cursor, Cline, ChatGPT) once connected to **APK-MCP** so it automatically understands your environment and toolset:

```text
You are connected to APK-MCP (Android APK Reverse Engineering & Modification Server).

YOUR AUTOMATED WORKFLOW & ZERO-FRICTION EXECUTION INSTRUCTIONS:
1. Fast APK Discovery & Single-Call Goal Analysis:
   - When the user mentions an APK name and a goal (e.g., "analyze subwaysurfers.apk for currency" or "find api keys in app-debug.apk"), AUTOMATICALLY call `apk_quick_analyze(apk_path="<apk_name>", goal="<goal>", mode="fast")` FIRST.
   - Do NOT search C:\, D:\, or disk drives manually. All APKs reside in `%USERPROFILE%\.apk-mcp\apks\`.

2. Goal-Driven Preferred Tools (Reduces 20 tool calls into 1-2 calls):
   - Single Entry Analysis: `apk_quick_analyze(apk_path, goal="currency|security|storage|network|overview", mode="fast"|"standard"|"deep")`
   - Target Investigation: `apk_investigate(goal, target="coin")`
   - Universal Parallel Search: `apk_search(query="coin", scope="all"|"native"|"il2cpp"|"dex"|"smali"|"resources")`
   - Parallel Batch Searches: `apk_search_batch(["coin", "currency", "wallet", "balance"])`
   - Engine Detection: `apk_detect_engine()` (Detects Unity IL2CPP, Mono, Flutter, React Native, Unreal, Android Native)
   - Persistent Index: `apk_index_build()`, `apk_index_status()` (SHA256 cached analysis)

3. Virtual Device & Live Verification (CRITICAL FOR BUG-FREE MODS):
   - Always test patched APKs on the connected Virtual Phone (`VirtualPhone_D`).
   - All-in-One Test Run: `device_test_run(package_name="com.kiloo.subwaysurf")` — Installs, launches app, monitors logcat, detects crashes/SIGSEGV, and captures a screenshot!
   - Crash Debugging: If an app closes or fails after patching, call `device_crash_log(package_name="...")` immediately to pull FATAL EXCEPTION stack traces, native SIGSEGV errors, or Unity log errors to diagnose and fix the patch.

4. Technology-Specific Execution Rules:
   - Unity IL2CPP Games: Call `il2cpp_dump()`, search with `il2cpp_search(query="Coin")`, patch with `native_patch_offset()`, then `rebuild_and_sign()`. Test on Virtual Phone using `device_test_run()`. Do NOT launch Ghidra unless metadata resolution fails!
   - Java/Kotlin Android Apps: Use `apk_search(query)` or `code_search_batch()`.
   - Native ELF Patching: Use `native_patch_offset(lib_name, offset_hex, hex_bytes)` to patch machine opcodes directly.

5. Guidelines for High-Efficiency Operations:
   - Avoid duplicate searches or single-keyword iterations. Use `apk_search_batch` for multiple terms.
   - Output signed APKs appear in: `%USERPROFILE%\.apk-mcp\output\`
```

Or get it anytime from the terminal:
```powershell
python -m apk_mcp.cli prompt
```

---

## User Workflow


1. Install APK-MCP with `.\install.ps1`
2. Connect APK-MCP to your MCP-compatible AI client
3. Put target `.apk` files into `%USERPROFILE%\.apk-mcp\apks\`
4. Tell your AI what to analyze or modify (e.g. *"Analyze app.apk and change the app label to My Test App"*)
5. AI automatically uses `apk-mcp` tools lazily and in isolated transactions
6. The modified, aligned, signed, and verified APK appears in `%USERPROFILE%\.apk-mcp\output\`

---

## Architecture Overview

```text
       ┌───────────────────────┐
       │     AI Agent (MCP)    │
       └───────────┬───────────┘
                   │
       ┌───────────▼───────────┐
       │        APK-MCP        │
       │  Orchestration Server │
       └───────────┬───────────┘
                   │
 ┌─────────┬───────┼───────┬─────────┐
 │         │       │       │         │
JADX    Apktool  AAPT2  Signer    ADB
```

---

## MCP Tools Offered

APK-MCP exposes 40+ granular and high-level tools grouped by category:

- **Project Tools**: `project.create`, `project.open`, `project.close`, `project.status`, `project.snapshot`
- **APK Inspection**: `apk.inspect`, `apk.metadata`, `apk.list_files`, `apk.read_file`, `apk.extract`
- **Code Analysis**: `code.search`, `code.list_classes`, `code.get_class`, `code.get_method`, `code.find_references`
- **Smali Editing**: `smali.search`, `smali.get_class`, `smali.get_method`, `smali.edit_method`
- **Manifest Editing**: `manifest.get`, `manifest.permissions`, `manifest.components`, `manifest.edit`
- **Resource Management**: `resource.list`, `resource.get`, `resource.search`, `resource.edit`, `resource.replace`
- **Build & Sign**: `build.validate`, `build_apk`, `sign.sign`, `sign.verify`
- **Device & Debugging**: `device.list`, `device.install`, `device.launch`, `device.logcat`, `device.screenshot`
- **High-Level Workflows**: `analyze_apk`, `find_feature`, `modify_app_name`, `rebuild_and_sign`

---

## Documentation

- [Windows Installation Guide](docs/INSTALL_WINDOWS.md)
- [MCP Client Setup Guide](docs/MCP_SETUP.md)
- [User Guide & Workflows](docs/USER_GUIDE.md)
- [Architecture & Design](docs/ARCHITECTURE.md)
- [Tools Reference](docs/TOOLS.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Security Boundaries](docs/SECURITY.md)
- [Development Guide](docs/DEVELOPMENT.md)

---

## License

MIT License.