Content
# 📱 Mobile App Testing MCP
An MCP Server for Android security testing scenarios, focusing on the following capabilities:
- ADB device and application operation automation
- AAPT APK information analysis
- JADX decompilation and code auditing support
- Static security scanning (key leakage, weak encryption, debugging leakage)
The project follows the standard `stdio` MCP protocol and can be connected to Claude, Codex, and other MCP clients.
## ✨ Core Features
- Out-of-the-box startup script: `npm start` will first detect dependencies and then start the service
- Automatically download JADX on the first run (default `v1.5.5`)
- Supports multiple levels of fallback for `.env`, Android SDK path, and system PATH
- Built-in health check link: `check` + `smoke` + `verify`
- Comprehensive static analysis can directly export a unified audit report (`json` / `md` / `sarif`)
- Added session pre-check and one-click reproduction pipeline (including evidence package `manifest.json`)
## 📌 Capability Boundary
- Currently positioned as **Android App Testing MCP**
- Frida / Gadget dynamic injection capabilities have been removed
- Dynamic Hook class testing is not within the scope of the current tool
## 🚀 Startup Process (Simplest)
```bash
# 1) Clone and enter the directory
git clone https://github.com/your-username/mobile-app-testing-mcp.git
cd mobile-app-testing-mcp
# 2) Install and build
npm run setup
# 3) Start MCP
npm start
```
Just these three steps, other configurations can be added later.
## 🔌 One-Click Installation to Client
```bash
# Install to Codex + Claude simultaneously
npm run install:mcp
# Install only to Codex
npm run install:mcp:codex
# Install only to Claude
npm run install:mcp:claude
```
The installation script will:
1. Automatically locate the client configuration file (`~/.codex/config.toml`, Claude Desktop configuration)
2. Write the `mobile-app-testing` MCP Server entry (pointing to `scripts/start.js`)
3. Automatically back up the original file before making changes (`.bak.<timestamp>`)
## 🧭 What `npm start` Does Automatically
`npm start` actually executes `node scripts/start.js`, and will automatically do the following before starting:
1. Detect the local path of `adb` / `aapt` / `jadx` (`.env`, Android SDK, PATH)
2. If `jadx` is missing and `AUTO_DOWNLOAD_JADX=true`, automatically download and unzip it
3. Print suggestions for fixing missing dependencies, and then start the service
Default JADX download address:
`https://github.com/skylot/jadx/releases/download/v1.5.5/jadx-1.5.5.zip`
## 🛠 Environment Requirements
- Node.js `>= 18`
- Android SDK (at least including `platform-tools`, recommended to include `build-tools`)
- JADX (optional, can be automatically downloaded by the startup script)
## ⚙️ Common Commands
```bash
npm run setup # Install dependencies + build
npm start # Start (including dependency detection and JADX automatic download)
npm run verify # Complete verification (build + check + smoke)
npm run check # Only check local dependencies
npm run smoke # Only do MCP smoke test
npm run build # Clean dist and recompile
npm run dev # Build and start (same as start)
```
## 🔧 `.env` Configuration
Copy `.env.example` to `.env`, and the common configurations are as follows:
- `ANDROID_HOME` / `ANDROID_SDK_ROOT`: Android SDK path (recommended setting)
- `ADB_PATH`: Absolute path to the adb executable (optional)
- `AAPT_PATH`: Absolute path to the aapt executable (optional)
- `JADX_PATH`: Absolute path to the jadx executable (optional)
- `EMULATOR_PATH`: Android emulator executable file path (optional, supports AVD list/start/stop)
- `AUTO_DOWNLOAD_JADX`: Whether to automatically download JADX (default `true`)
- `JADX_VERSION`: Automatically download version (default `1.5.5`)
- `JADX_DOWNLOAD_URL`: JADX download URL (can override the default address)
- `SCREENSHOTS_DIR` / `RECORDINGS_DIR` / `DECOMPILED_DIR` / `LOGS_DIR`: Working directory
## 🔌 MCP Client Access
The project is a standard `stdio` MCP Server, and the general configuration is as follows:
```json
{
"mcpServers": {
"mobile-app-testing": {
"command": "node",
"args": ["/path/to/your/project/scripts/start.js"],
"cwd": "/path/to/your/project",
"env": {}
}
}
}
```
Instructions:
- `args` is recommended to point to `scripts/start.js` (instead of `dist/index.js`), in order to retain automatic dependency checking and JADX first-time download
- `cwd` is recommended to be the project root directory
- When the client does not inherit the system environment, please explicitly pass in `ANDROID_HOME` and `PATH` in `env`
Example file: [`mcp-config.example.json`](./mcp-config.example.json)
## 🧰 Tool Capability List
Currently a total of `46` tools:
- ADB Tools `25`: Device, emulator (AVD list/start/stop), application, file, input simulation, screenshot recording
- AAPT Tools `4`: badging, permissions, xmltree, complete analysis
- JADX Tools `3`: Decompilation, output information, APK verification
- Static Analysis Tools `4`: secrets/debug/weak-crypto/comprehensive (including unified report export)
- Workflow Tools `9`: Template, context, intelligent suggestion, execution record, session pre-check, evidence package export, one-click reproduction pipeline
- File Tools `1`: `sha256` fingerprint
## 💡 Usage Example
In any MCP client, you can directly propose:
```text
Analyze the basic information of this APK: /path/to/app.apk
Decompile this APK and output the key directory: /path/to/app.apk
Take a screenshot of the currently connected device and save it to the default directory
View the available emulators and start: adb_list_emulators / adb_start_emulator
Close the emulator: adb_stop_emulator (or specify emulator_id)
Do a comprehensive static analysis of the decompiled directory and export json/md/sarif reports to /tmp/reports
First do a session pre-check: workflow_session_precheck
Execute the one-click reproduction pipeline and export the evidence package: workflow_run_repro_pipeline
```
`static_comprehensive_analysis` supports optional parameters:
- `output_formats`: Any combination of `["json","md","sarif"]`
- `output_dir`: Report output directory (default `./reports`)
- `report_name`: Report file name prefix
- `include_third_party`: Whether to include third-party library directory (default `false`)
- `third_party_prefixes`: Custom third-party path prefix
`static_scan_secrets` / `static_scan_debug_leaks` / `static_scan_weak_crypto` / `static_comprehensive_analysis` all output a unified field model:
- `severity` / `cwe` / `masvs` / `evidence` / `repro` / `impact` / `fix`
`adb_start_app` / `adb_screenshot` / `adb_shell_command` support stability parameters:
- `timeout_ms`: Timeout control
- `retry_count`: Number of retries
- `retry_delay_ms`: Retry interval
`adb_start_emulator` supports startup waiting parameters:
- `wait_for_ready`: Whether to wait for the emulator to be ready (default `true`)
- `wait_for_boot_completed`: Whether to wait for `sys.boot_completed=1` (default `true`)
- `timeout_ms` / `poll_interval_ms`: Startup waiting timeout and polling interval
`adb_install_app` supports installation waiting parameters:
- `timeout_ms` / `retry_count` / `retry_delay_ms`: Timeout and retry for installation execution
- `wait_after_install_ms`: Extra wait after successful installation (default `3000`)
## 📚 Prompt Examples
Reference [`prompt-examples`](./prompt-examples/):
- [SECURITY_TESTING_PROMPT](./prompt-examples/SECURITY_TESTING_PROMPT.md)
- [Static Code Security Analysis](./prompt-examples/静态代码安全分析.md)
- [Network Communication Encryption Analysis](./prompt-examples/网络通信加密分析.md)
- [Root Detection Bypass Analysis](./prompt-examples/Root检测绕过分析.md)
- [SSL Certificate Pinning Bypass](./prompt-examples/SSL证书固定绕过.md)
- [Application Shelling and Unpacking Analysis](./prompt-examples/应用加壳脱壳分析.md)
- [Malware Behavior Analysis](./prompt-examples/恶意软件行为分析.md)
## 🆘 Common Issues
### 1) Want the Easiest Startup
```bash
npm run setup
npm start
```
If it can start, you don't need to run `check/smoke/verify` first.
### 2) `npm start` Prompts Missing `adb` / `aapt`
First execute:
```bash
npm run check
```
Then set `ANDROID_HOME` or `ADB_PATH` / `AAPT_PATH` according to the output prompt.
### 3) `jadx` Missing
- Keep `AUTO_DOWNLOAD_JADX=true`, and it will automatically download on the first startup
- Or manually install and set `JADX_PATH`
- If you need to fix the download source, set `JADX_DOWNLOAD_URL`
### 4) Client Cannot Connect to MCP
- Confirm that `args` is an absolute path and points to `scripts/start.js`
- Confirm that `cwd` points to the project root directory
- Run `npm run verify` first to rule out server-side issues
- You can re-execute `npm run install:mcp` to overwrite and update the client configuration
### 5) Device Shows `unauthorized`
```bash
adb devices
```
Confirm USB debugging authorization on the phone and try again.
## 🔐 Compliance Statement
- Only for legally authorized security testing and research
- Please comply with local laws and regulations and organizational compliance requirements
- It is forbidden to use it for unauthorized targets or malicious purposes
