📱 Mobile App Testing MCP

一个面向 Android 安全测试场景的 MCP Server，聚焦以下能力：

• ADB 设备与应用操作自动化
• AAPT APK 信息分析
• JADX 反编译与代码审计支撑
• 静态安全扫描（密钥泄露、弱加密、调试泄露）

项目遵循标准 stdio MCP 协议，可接入 Claude、Codex 及其他 MCP 客户端。

✨ 核心特性

• 开箱即用启动脚本：npm start 会先做依赖探测再启动服务
• 首次运行可自动下载 JADX（默认 v1.5.5）
• 支持 .env、Android SDK 路径、系统 PATH 多层回退
• 内置健康检查链路：check + smoke + verify
• 综合静态分析可直接导出统一审计报告（json / md / sarif）
• 新增会话预检与一键复现流水线（含证据包 manifest.json）

📌 能力边界

• 当前定位为 Android App 测试 MCP
• 已移除 Frida / Gadget 动态注入能力
• 动态 Hook 类测试不在当前工具范围内

🚀 启动流程（最简）

# 1) 克隆并进入目录
git clone https://github.com/your-username/mobile-app-testing-mcp.git
cd mobile-app-testing-mcp

# 2) 安装并构建
npm run setup

# 3) 启动 MCP
npm start

就这三步，其他配置都可以后补。

🔌 一键安装到客户端

# 同时安装到 Codex + Claude
npm run install:mcp

# 仅安装到 Codex
npm run install:mcp:codex

# 仅安装到 Claude
npm run install:mcp:claude

安装脚本会：

1. 自动定位客户端配置文件（~/.codex/config.toml、Claude Desktop 配置）
2. 写入 mobile-app-testing MCP Server 条目（指向 scripts/start.js）
3. 变更前自动备份原文件（.bak.<timestamp>）

🧭 npm start 会自动做什么

npm start 实际执行 node scripts/start.js，启动前会自动：

1. 探测 adb / aapt / jadx 本地路径（.env、Android SDK、PATH）
2. 若缺少 jadx 且 AUTO_DOWNLOAD_JADX=true，自动下载并解压
3. 打印缺失依赖修复建议后，再启动服务

默认 JADX 下载地址： https://github.com/skylot/jadx/releases/download/v1.5.5/jadx-1.5.5.zip

🛠 环境要求

• Node.js >= 18
• Android SDK（至少包含 platform-tools，推荐包含 build-tools）
• JADX（可选，可由启动脚本自动下载）

⚙️ 常用命令

npm run setup    # 安装依赖 + 构建
npm start        # 启动（含依赖探测与JADX自动下载）
npm run verify   # 完整验证（build + check + smoke）
npm run check    # 仅检查本机依赖
npm run smoke    # 仅做 MCP 冒烟测试
npm run build    # 清理 dist 后重新编译
npm run dev      # 构建后启动（同 start）

🔧 .env 配置

复制 .env.example 为 .env 后，常用配置如下：

• ANDROID_HOME / ANDROID_SDK_ROOT：Android SDK 路径（推荐设置）
• ADB_PATH：adb 可执行文件绝对路径（可选）
• AAPT_PATH：aapt 可执行文件绝对路径（可选）
• JADX_PATH：jadx 可执行文件绝对路径（可选）
• EMULATOR_PATH：Android emulator 可执行文件路径（可选，支持 AVD 列表/启动/关闭）
• AUTO_DOWNLOAD_JADX：是否自动下载 JADX（默认 true）
• JADX_VERSION：自动下载版本（默认 1.5.5）
• JADX_DOWNLOAD_URL：JADX 下载 URL（可覆盖默认地址）
• SCREENSHOTS_DIR / RECORDINGS_DIR / DECOMPILED_DIR / LOGS_DIR：工作目录

🔌 MCP 客户端接入

项目是标准 stdio MCP Server，通用配置如下：

{
  "mcpServers": {
    "mobile-app-testing": {
      "command": "node",
      "args": ["/path/to/your/project/scripts/start.js"],
      "cwd": "/path/to/your/project",
      "env": {}
    }
  }
}

说明：

• args 推荐指向 scripts/start.js（而不是 dist/index.js），才能保留自动依赖检查与 JADX 首启下载
• cwd 建议为项目根目录
• 客户端不继承系统环境时，请在 env 明确传入 ANDROID_HOME、PATH

示例文件：mcp-config.example.json

🧰 工具能力清单

当前总计 46 个工具：

• ADB 工具 25：设备、模拟器（AVD 列表/启动/关闭）、应用、文件、输入模拟、截屏录屏
• AAPT 工具 4：badging、permissions、xmltree、完整分析
• JADX 工具 3：反编译、输出信息、APK 验证
• 静态分析工具 4：secrets/debug/weak-crypto/comprehensive（含统一报告导出）
• 工作流工具 9：模板、上下文、智能建议、执行记录、会话预检、证据包导出、一键复现流水线
• 文件工具 1：sha256 指纹

💡 使用示例

在任意 MCP 客户端可直接提出：

分析这个 APK 的基础信息：/path/to/app.apk
反编译这个 APK 并输出关键目录：/path/to/app.apk
对当前连接设备截图并保存到默认目录
查看可启动模拟器并启动：adb_list_emulators / adb_start_emulator
关闭模拟器：adb_stop_emulator（或指定 emulator_id）
对反编译目录做全面静态分析，并导出 json/md/sarif 报告到 /tmp/reports
先做会话预检：workflow_session_precheck
执行一键复现流水线并导出证据包：workflow_run_repro_pipeline

static_comprehensive_analysis 支持可选参数：

• output_formats: ["json","md","sarif"] 中的任意组合
• output_dir: 报告输出目录（默认 ./reports）
• report_name: 报告文件名前缀
• include_third_party: 是否包含第三方库目录（默认 false）
• third_party_prefixes: 自定义第三方路径前缀

static_scan_secrets / static_scan_debug_leaks / static_scan_weak_crypto / static_comprehensive_analysis 均输出统一字段模型：

• severity / cwe / masvs / evidence / repro / impact / fix

adb_start_app / adb_screenshot / adb_shell_command 支持稳定性参数：

• timeout_ms: 超时控制
• retry_count: 重试次数
• retry_delay_ms: 重试间隔

adb_start_emulator 支持启动等待参数：

• wait_for_ready: 是否等待模拟器就绪（默认 true）
• wait_for_boot_completed: 是否等待 sys.boot_completed=1（默认 true）
• timeout_ms / poll_interval_ms: 启动等待超时与轮询间隔

adb_install_app 支持安装等待参数：

• timeout_ms / retry_count / retry_delay_ms: 安装执行的超时与重试
• wait_after_install_ms: 安装成功后额外等待（默认 3000）

📚 Prompt 示例

参考 prompt-examples：

• SECURITY_TESTING_PROMPT
• 静态代码安全分析
• 网络通信加密分析
• Root检测绕过分析
• SSL证书固定绕过
• 应用加壳脱壳分析
• 恶意软件行为分析

🆘 常见问题

1) 想要最省事启动

npm run setup
npm start

如果能启动，就不需要先跑 check/smoke/verify。

2) npm start 提示缺少 adb / aapt

先执行：

npm run check

然后按输出提示设置 ANDROID_HOME 或 ADB_PATH / AAPT_PATH。

3) jadx 缺失

• 保持 AUTO_DOWNLOAD_JADX=true，首次启动会自动下载
• 或手动安装后设置 JADX_PATH
• 如需固定下载源，设置 JADX_DOWNLOAD_URL

4) 客户端连不上 MCP

• 确认 args 是绝对路径且指向 scripts/start.js
• 确认 cwd 指向项目根目录
• 先运行 npm run verify 排除服务端问题
• 可重新执行 npm run install:mcp 覆盖更新客户端配置

5) 设备显示 unauthorized

adb devices

在手机上确认 USB 调试授权后重试。

🔐 合规说明

• 仅用于合法授权的安全测试与研究
• 请遵守所在地法律法规与组织合规要求
• 禁止用于未授权目标或恶意用途