Android Reverse MCP Server

中文

Android Reverse MCP Server，也叫 AndroidMcp，是一个面向授权 Android 安全研究的 MCP 服务。

它由电脑侧 MCP Server、电脑侧 WebUI、Android 端 APatch/FolkPatch/Magisk 兼容模块组成。AI 工具可以通过 MCP 查询 Android 设备状态、读取目标 App 信息、观察进程和文件状态，并执行受控自动化动作。

本项目优先面向 root 研究设备。当前设备侧已经按 APatch/FolkPatch 兼容模块方式验收通过，同时保留 Magisk/Zygisk 模块目录结构。

项目定位

本项目不是普通手机远控工具，也不是面向普通用户的手机管理软件。它的目标是给安全研究员和 AI Agent 提供一个结构化 Android 研究接口。

典型用途：

查询连接的 Android 设备。
查询 root、SELinux、模块状态。
查询目标 App 包信息、签名、权限、组件。
查询目标 App 进程、任务栈、数据目录。
查询 fd、so 加载、网络连接等研究信息。
截图和执行低风险自动化动作。
通过 MCP 接入 Claude、Cursor、Codex、Cline 或自研 Agent。
通过 WebUI 查看状态、保存配置、调用工具和查看审计日志。

安全边界

仅用于：

自有设备。
实验设备。
授权测试设备。
明确授权的安全研究环境。

不提供默认能力用于：

未授权读取第三方数据。
隐藏模块或规避检测。
绕过支付、风控或访问控制。
后台静默执行高风险操作。
公网暴露远程控制接口。

架构

MCP Client / AI Tool
        |
        | MCP stdio
        v
PC-side AndroidMcp Server
        |
        | ADB bootstrap + root shell helper
        v
Android module under /data/adb/modules/androidmcp
        |
        | androidmcpctl
        v
Rooted Android research device

电脑侧组件：

server/android_mcp: Python MCP Server。
server/android_mcp/web.py: 本地 WebUI。
scripts/*.ps1: 构建、部署、测试脚本。

Android 端组件：

android-zygisk/module/module.prop: 模块元数据。
android-zygisk/module/bin/androidmcpctl: 设备端查询 helper。
android-zygisk/module/zygisk/arm64-v8a.so: native 模块产物。
android-zygisk/module/webroot/index.html: 模块管理器 WebUI 入口。
android-zygisk/module/action.sh: 模块管理器点击入口兜底。

当前状态

当前版本：0.2.1

已完成：

Python stdio MCP Server。
WebUI 状态和配置面板。
APatch/FolkPatch 兼容手动安装流程。
模块管理器 WebUI 入口：webroot/index.html。
模块管理器 action 入口：action.sh。
ADB/root shell transport。
包信息、签名、manifest、组件、权限查询。
进程、任务栈、数据目录、SharedPreferences、fd、so、网络连接 raw 查询。
截图、点击、滑动、输入、按键工具。
包名 allowlist。
审计日志。
Python、Kotlin service、NDK native、模块打包构建脚本。

仍在进行：

真正的 Zygisk API 接入。
Kotlin/Native daemon 替代 shell helper。
更稳定的结构化 dumpsys/parser。
长输出分块传输。
更完整的模块管理器内嵌交互页面。

环境要求

电脑侧：

Windows PowerShell。
Python 3.11 或更新版本。
Android SDK Platform Tools，也就是 adb。
Android NDK。
CMake 和 Ninja，推荐使用 Android SDK 自带版本。
Kotlin compiler，当前脚本可使用 IntelliJ IDEA 自带 kotlinc。

设备侧：

已 root Android 设备。
APatch、FolkPatch、KernelSU 或 Magisk 类 /data/adb/modules 模块环境。
已开启 USB 调试。
电脑已获得 ADB 授权。

构建

从仓库根目录执行：

powershell -ExecutionPolicy Bypass -File scripts\build-all.ps1

该命令会执行：

Python compileall。
Kotlin service 编译。
Android NDK/CMake 编译 arm64-v8a.so。
打包模块 zip。

输出：

dist/androidmcp-magisk.zip
android-zygisk/module/zygisk/arm64-v8a.so
build/service/androidmcp-service.jar

如需覆盖工具路径，可设置：

$env:ANDROID_MCP_PYTHON = "C:\Path\To\python.exe"
$env:ANDROID_SDK_ROOT = "C:\Path\To\Android\Sdk"
$env:ANDROID_NDK_HOME = "C:\Path\To\Android\Sdk\ndk\28.2.13676358"
$env:ANDROID_MCP_KOTLINC = "C:\Path\To\kotlinc.bat"

安装到 APatch/FolkPatch 设备

先连接设备：

adb devices -l

手动兼容安装：

powershell -ExecutionPolicy Bypass -File scripts\deploy-module.ps1 -Device <device_id> -InstallMode manual

安装路径：

/data/adb/modules/androidmcp

安装后建议重启设备，让模块管理器重新识别 module.prop、webroot 和 action.sh。

检查设备端版本：

adb -s <device_id> shell su -c /system/bin/cat /data/adb/modules/androidmcp/module.prop

预期包含：

version=0.2.1
versionCode=3

模块管理器 WebUI 入口

模块内置：

android-zygisk/module/webroot/index.html

APatch/FolkPatch/KernelSU 兼容管理器通常会在检测到 webroot 后显示 WebUI 按钮。

同时内置：

android-zygisk/module/action.sh

用于管理器支持 action 按钮但不支持 WebUI 按钮时的兜底。

模块内 WebUI 主要用于提示和跳转。完整控制台运行在电脑侧：

http://127.0.0.1:8765

如果要从手机打开电脑侧 WebUI，可以先执行：

adb reverse tcp:8765 tcp:8765

然后在手机里打开：

http://127.0.0.1:8765

启动电脑侧 WebUI

powershell -ExecutionPolicy Bypass -File scripts\webui.ps1

默认地址：

http://127.0.0.1:8765

WebUI 支持：

查看设备列表。
查看 root/module/Zygisk 状态。
保存 ADB 路径、默认设备、allowlist 等配置。
调用 MCP 工具。
查看审计日志。

配置文件默认写入：

server/android_mcp_config.json

MCP Client 配置

示例：

{
  "mcpServers": {
    "android-mcp": {
      "command": "python",
      "args": ["-m", "android_mcp"],
      "cwd": "C:\\Users\\Administrator\\Desktop\\AndroidMcp\\server",
      "env": {
        "ANDROID_MCP_ADB": "C:\\Users\\Administrator\\AppData\\Local\\Android\\Sdk\\platform-tools\\adb.exe",
        "ANDROID_MCP_DEVICE": "e475a4fb",
        "ANDROID_MCP_ALLOWED_PACKAGES": "com.android.settings",
        "ANDROID_MCP_AUDIT": "1"
      }
    }
  }
}

也可以安装本地包后使用 console scripts：

python -m pip install -e server
android-mcp --help
android-mcp-web --help

常用 MCP 工具

设备：

android.list_devices
android.get_device_info
android.get_foreground_app
android.take_screenshot

模块：

android.zygisk_status
android.zygisk_get_capabilities
android.zygisk_get_selinux

App 研究：

android.app.get_package_info
android.app.get_signature_info
android.app.get_manifest
android.app.list_components
android.app.list_permissions
android.app.get_processes
android.app.get_task_stack
android.app.list_data_files
android.app.read_file
android.app.hash_file
android.app.list_preferences
android.app.list_loaded_libraries
android.app.list_fds
android.app.list_network_connections

自动化：

android.tap
android.swipe
android.input_text
android.press_key

Allowlist

电脑侧 allowlist：

$env:ANDROID_MCP_ALLOWED_PACKAGES = "com.android.settings,com.example.target"

设备侧 allowlist：

/data/adb/androidmcp/allowed_packages.txt

一行一个包名：

com.android.settings
com.example.target

如果设备侧文件存在，androidmcpctl 会拒绝不在列表里的包名。

验收测试

完整构建：

powershell -ExecutionPolicy Bypass -File scripts\build-all.ps1

设备 smoke：

powershell -ExecutionPolicy Bypass -File scripts\smoke-device.ps1 -Device <device_id> -Package com.android.settings

WebUI：

powershell -ExecutionPolicy Bypass -File scripts\webui.ps1

访问：

http://127.0.0.1:8765/api/status

已知限制

当前 Android 端主要通过 androidmcpctl shell helper 实现，长输出会被截断。
service_state 可能显示 unknown，因为本阶段还未启用长期运行的 native/Kotlin daemon。
zygisk/arm64-v8a.so 已能编译和打包，但还不是完整 Zygisk API 模块。
部分 App 信息来自 dumpsys raw 输出，后续需要结构化 parser。
当前主要验收目标是 APatch/FolkPatch 兼容 root 设备。

目录结构

AndroidMcp/
  server/                 PC-side MCP server and WebUI
  android-zygisk/         Android module, native scaffold and service scaffold
  scripts/                Build, deploy, smoke and WebUI scripts
  docs/                   Extra documentation
  READNE.md               Original planning document

English

Android Reverse MCP Server, also called AndroidMcp, is an MCP server for authorized Android security research.

It consists of a PC-side MCP server, a PC-side WebUI, and an Android-side APatch/FolkPatch/Magisk-compatible module. MCP-capable AI tools can query Android device state, inspect target App metadata, observe process/file state, and execute controlled automation actions.

The project is root-device first. The current module has been validated through an APatch/FolkPatch-compatible manual install flow, while keeping a Magisk/Zygisk-style module layout.

Purpose

This is not a consumer phone remote-control app. It is designed as a structured Android research interface for security researchers and AI agents.

Typical use cases:

List connected Android devices.
Query root, SELinux and module state.
Inspect target App package info, signatures, permissions and components.
Inspect process state, task stack and data directories.
Inspect fd, loaded libraries and network raw views.
Capture screenshots and run low-risk automation.
Connect Claude, Cursor, Codex, Cline or custom agents through MCP.
Use the WebUI to view status, save configuration, call tools and inspect audit logs.

Security Boundary

Use only on:

Devices you own.
Lab devices.
Authorized test devices.
Explicitly authorized research environments.

This project does not provide default capabilities for:

Unauthorized third-party data access.
Hiding modules or evading detection.
Bypassing payment, risk-control or access-control systems.
Silent background execution of high-risk actions.
Exposing remote control over the public internet.

Architecture

MCP Client / AI Tool
        |
        | MCP stdio
        v
PC-side AndroidMcp Server
        |
        | ADB bootstrap + root shell helper
        v
Android module under /data/adb/modules/androidmcp
        |
        | androidmcpctl
        v
Rooted Android research device

PC-side components:

server/android_mcp: Python MCP server.
server/android_mcp/web.py: local WebUI.
scripts/*.ps1: build, deploy and smoke scripts.

Android-side components:

android-zygisk/module/module.prop: module metadata.
android-zygisk/module/bin/androidmcpctl: device-side helper.
android-zygisk/module/zygisk/arm64-v8a.so: native module artifact.
android-zygisk/module/webroot/index.html: module-manager WebUI entry.
android-zygisk/module/action.sh: fallback action entry.

Current Status

Current version: 0.2.1

Implemented:

Python stdio MCP server.
Local WebUI for status and configuration.
APatch/FolkPatch-compatible manual install flow.
Module-manager WebUI entry via webroot/index.html.
Module-manager action entry via action.sh.
ADB/root shell transport.
Package info, signature, manifest, component and permission queries.
Process, task stack, data directory, SharedPreferences, fd, loaded-library and network raw queries.
Screenshot, tap, swipe, text input and key event tools.
Package allowlist.
Audit logging.
Build scripts for Python, Kotlin service, Android NDK native code and module packaging.

In progress:

Real Zygisk API integration.
Kotlin/Native daemon to replace the shell helper.
Stable structured parsers for dumpsys/proc output.
Chunked transport for large outputs.
More complete in-module interactive WebUI.

Requirements

PC:

Windows PowerShell.
Python 3.11 or newer.
Android SDK Platform Tools, including adb.
Android NDK.
CMake and Ninja, preferably from Android SDK.
Kotlin compiler. The current scripts can use IntelliJ IDEA's bundled kotlinc.

Device:

Rooted Android device.
APatch, FolkPatch, KernelSU or Magisk-like /data/adb/modules environment.
USB debugging enabled.
ADB authorization granted to the PC.

Build

Run from the repository root:

powershell -ExecutionPolicy Bypass -File scripts\build-all.ps1

This runs:

Python compileall.
Kotlin service compile.
Android NDK/CMake compile for arm64-v8a.so.
Module zip packaging.

Outputs:

dist/AndroidMcp_APatch_Zygisk_<version>.zip
android-zygisk/module/zygisk/arm64-v8a.so
build/service/androidmcp-service.jar

Override tool paths if needed:

$env:ANDROID_MCP_PYTHON = "C:\Path\To\python.exe"
$env:ANDROID_SDK_ROOT = "C:\Path\To\Android\Sdk"
$env:ANDROID_NDK_HOME = "C:\Path\To\Android\Sdk\ndk\28.2.13676358"
$env:ANDROID_MCP_KOTLINC = "C:\Path\To\kotlinc.bat"

Install on APatch/FolkPatch Device

List devices:

adb devices -l

Install using the compatible manual flow:

powershell -ExecutionPolicy Bypass -File scripts\deploy-module.ps1 -Device <device_id> -InstallMode manual

Install path:

/data/adb/modules/androidmcp

Reboot after installation so the module manager can refresh module.prop, webroot and action.sh.

Check the installed version:

adb -s <device_id> shell su -c /system/bin/cat /data/adb/modules/androidmcp/module.prop

Expected:

version=0.2.1
versionCode=3

Module Manager WebUI Entry

The module includes:

android-zygisk/module/webroot/index.html

APatch/FolkPatch/KernelSU-compatible managers usually show a WebUI button when this directory exists.

It also includes:

android-zygisk/module/action.sh

This is a fallback for managers that expose action buttons instead of WebUI buttons.

The module WebUI is a lightweight entry and help page. The full dashboard runs on the PC:

http://127.0.0.1:8765

To open the PC WebUI from the phone:

adb reverse tcp:8765 tcp:8765

Then open on the phone:

http://127.0.0.1:8765

Start PC-side WebUI

powershell -ExecutionPolicy Bypass -File scripts\webui.ps1

Default URL:

http://127.0.0.1:8765

The WebUI supports:

Device list.
Root/module/Zygisk status.
Configuration for ADB path, default device and allowlist.
MCP tool calls.
Audit log viewer.

Default config file:

server/android_mcp_config.json

MCP Client Configuration

Example:

{
  "mcpServers": {
    "android-mcp": {
      "command": "python",
      "args": ["-m", "android_mcp"],
      "cwd": "C:\\Users\\Administrator\\Desktop\\AndroidMcp\\server",
      "env": {
        "ANDROID_MCP_ADB": "C:\\Users\\Administrator\\AppData\\Local\\Android\\Sdk\\platform-tools\\adb.exe",
        "ANDROID_MCP_DEVICE": "e475a4fb",
        "ANDROID_MCP_ALLOWED_PACKAGES": "com.android.settings",
        "ANDROID_MCP_AUDIT": "1"
      }
    }
  }
}

Install local console scripts:

python -m pip install -e server
android-mcp --help
android-mcp-web --help

Common MCP Tools

Device:

android.list_devices
android.get_device_info
android.get_foreground_app
android.take_screenshot

Module:

android.zygisk_status
android.zygisk_get_capabilities
android.zygisk_get_selinux

App research:

android.app.get_package_info
android.app.get_signature_info
android.app.get_manifest
android.app.list_components
android.app.list_permissions
android.app.get_processes
android.app.get_task_stack
android.app.list_data_files
android.app.read_file
android.app.hash_file
android.app.list_preferences
android.app.list_loaded_libraries
android.app.list_fds
android.app.list_network_connections

Automation:

android.tap
android.swipe
android.input_text
android.press_key

Allowlist

PC-side allowlist:

$env:ANDROID_MCP_ALLOWED_PACKAGES = "com.android.settings,com.example.target"

Device-side allowlist:

/data/adb/androidmcp/allowed_packages.txt

One package per line:

com.android.settings
com.example.target

If the device-side file exists, androidmcpctl rejects packages not listed in it.

Acceptance Tests

Full build:

powershell -ExecutionPolicy Bypass -File scripts\build-all.ps1

Device smoke:

powershell -ExecutionPolicy Bypass -File scripts\smoke-device.ps1 -Device <device_id> -Package com.android.settings

WebUI:

powershell -ExecutionPolicy Bypass -File scripts\webui.ps1

Open:

http://127.0.0.1:8765/api/status

Known Limitations

Android-side logic currently uses the androidmcpctl shell helper.
Large raw outputs are truncated.
service_state may show unknown because the long-running native/Kotlin daemon is not enabled yet.
zygisk/arm64-v8a.so builds and packages, but it is not yet a complete Zygisk API module.
Some App information is raw dumpsys output and needs structured parsers.
Current validation focuses on APatch/FolkPatch-compatible root devices.

Repository Layout

AndroidMcp/
  server/                 PC-side MCP server and WebUI
  android-zygisk/         Android module, native scaffold and service scaffold
  scripts/                Build, deploy, smoke and WebUI scripts
  docs/                   Extra documentation
  READNE.md               Original planning document

Name		Name	Last commit message	Last commit date
android-zygisk		android-zygisk
docs		docs
scripts		scripts
server		server
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
READNE.md		READNE.md

Latest commit

History

Folders and files

Repository files navigation

Android Reverse MCP Server

中文

项目定位

安全边界

架构

当前状态

环境要求

构建

安装到 APatch/FolkPatch 设备

模块管理器 WebUI 入口

启动电脑侧 WebUI

MCP Client 配置

常用 MCP 工具

Allowlist

验收测试

已知限制

目录结构

相关文档

English

Purpose

Security Boundary

Architecture

Current Status

Requirements

Build

Install on APatch/FolkPatch Device

Module Manager WebUI Entry

Start PC-side WebUI

MCP Client Configuration

Common MCP Tools

Allowlist

Acceptance Tests

Known Limitations

Repository Layout

Documentation

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages