android-re-mcp 1.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- android_re_mcp-1.4.0/.gitignore +50 -0
- android_re_mcp-1.4.0/LICENSE +23 -0
- android_re_mcp-1.4.0/NOTICE.md +4 -0
- android_re_mcp-1.4.0/PKG-INFO +113 -0
- android_re_mcp-1.4.0/README.md +66 -0
- android_re_mcp-1.4.0/pyproject.toml +57 -0
- android_re_mcp-1.4.0/src/android_re_mcp/__init__.py +11 -0
- android_re_mcp-1.4.0/src/android_re_mcp/__main__.py +90 -0
- android_re_mcp-1.4.0/src/android_re_mcp/clitools.py +48 -0
- android_re_mcp-1.4.0/src/android_re_mcp/config.py +38 -0
- android_re_mcp-1.4.0/src/android_re_mcp/config.toml +9 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/__init__.py +1 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/build_bundles.sh +56 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/crypto_monitor.js +13776 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/frida_detection_bypass.js +13767 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/index.py +127 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/memory_scan.js +140 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/method_tracer.js +13742 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/network_monitor.js +13774 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/root_detection_bypass.js +13809 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/src/crypto_monitor.js +124 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/src/frida_detection_bypass.js +124 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/src/method_tracer.js +95 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/src/network_monitor.js +128 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/src/root_detection_bypass.js +139 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/src/ssl_pinning_universal.js +105 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/src/storage_monitor.js +155 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/ssl_pinning_universal.js +13756 -0
- android_re_mcp-1.4.0/src/android_re_mcp/frida_scripts/storage_monitor.js +13782 -0
- android_re_mcp-1.4.0/src/android_re_mcp/guard.py +132 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/__init__.py +1 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/apiextractor.py +183 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/apkdiff.py +333 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/apkscan.py +151 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/device.py +660 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/dynamic.py +816 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/flutter.py +345 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/googleservices.py +209 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/memory.py +85 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/native.py +731 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/network.py +379 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/patcher.py +377 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/rasp.py +389 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/signing.py +91 -0
- android_re_mcp-1.4.0/src/android_re_mcp/handlers/static.py +1154 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/bypass-frida.md +37 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/bypass-playbooks.md +122 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/bypass-root.md +36 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/bypass-ssl.md +25 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/common-mistakes.md +74 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/crypto-patterns.md +91 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/detection-patterns.md +107 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/first-look.md +41 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/framework-fingerprints.md +93 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/master-agent-workflow.md +32 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/rasp-assess.md +58 -0
- android_re_mcp-1.4.0/src/android_re_mcp/knowledge/stuck.md +35 -0
- android_re_mcp-1.4.0/src/android_re_mcp/paths.py +69 -0
- android_re_mcp-1.4.0/src/android_re_mcp/server.py +1386 -0
- android_re_mcp-1.4.0/src/android_re_mcp/setup/__init__.py +1 -0
- android_re_mcp-1.4.0/src/android_re_mcp/setup/check_tools.py +377 -0
- android_re_mcp-1.4.0/src/android_re_mcp/setup/install_tool.py +342 -0
- android_re_mcp-1.4.0/tests/conftest.py +15 -0
- android_re_mcp-1.4.0/tests/fixtures/build_notesdemo.sh +46 -0
- android_re_mcp-1.4.0/tests/fixtures/notesdemo/AndroidManifest.xml +49 -0
- android_re_mcp-1.4.0/tests/test_adb_ui_dump.py +109 -0
- android_re_mcp-1.4.0/tests/test_androguard_tools.py +372 -0
- android_re_mcp-1.4.0/tests/test_api_extractor.py +113 -0
- android_re_mcp-1.4.0/tests/test_apk_diff.py +199 -0
- android_re_mcp-1.4.0/tests/test_check_tools_honesty.py +170 -0
- android_re_mcp-1.4.0/tests/test_concurrency.py +130 -0
- android_re_mcp-1.4.0/tests/test_frida_config_protocol.py +337 -0
- android_re_mcp-1.4.0/tests/test_frida_status.py +110 -0
- android_re_mcp-1.4.0/tests/test_google_services.py +210 -0
- android_re_mcp-1.4.0/tests/test_guard.py +85 -0
- android_re_mcp-1.4.0/tests/test_handlers.py +232 -0
- android_re_mcp-1.4.0/tests/test_native_inventory.py +224 -0
- android_re_mcp-1.4.0/tests/test_quark_scan.py +137 -0
- android_re_mcp-1.4.0/tests/test_server.py +67 -0
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Build output
|
|
2
|
+
dist/
|
|
3
|
+
|
|
4
|
+
# Dependencies
|
|
5
|
+
node_modules/
|
|
6
|
+
|
|
7
|
+
# APK / IPA — never commit binary test files
|
|
8
|
+
*.apk
|
|
9
|
+
*.ipa
|
|
10
|
+
*.aab
|
|
11
|
+
# ...except our own 5 KB fixture (built by tests/fixtures/build_notesdemo.sh)
|
|
12
|
+
!python/tests/fixtures/notesdemo.apk
|
|
13
|
+
|
|
14
|
+
# apktool / decompiled output folders
|
|
15
|
+
*_decompiled/
|
|
16
|
+
smali*/
|
|
17
|
+
baksmali*/
|
|
18
|
+
|
|
19
|
+
# Environment & secrets
|
|
20
|
+
.env
|
|
21
|
+
.env.*
|
|
22
|
+
*.keystore
|
|
23
|
+
*.jks
|
|
24
|
+
|
|
25
|
+
# OS
|
|
26
|
+
.DS_Store
|
|
27
|
+
Thumbs.db
|
|
28
|
+
|
|
29
|
+
# Editor
|
|
30
|
+
.vscode/
|
|
31
|
+
.idea/
|
|
32
|
+
*.swp
|
|
33
|
+
*.swo
|
|
34
|
+
|
|
35
|
+
# Logs
|
|
36
|
+
*.log
|
|
37
|
+
npm-debug.log*
|
|
38
|
+
|
|
39
|
+
# Claude memory (local only)
|
|
40
|
+
.claude/
|
|
41
|
+
|
|
42
|
+
# Python
|
|
43
|
+
__pycache__/
|
|
44
|
+
*.py[cod]
|
|
45
|
+
*.egg-info/
|
|
46
|
+
.venv/
|
|
47
|
+
.pytest_cache/
|
|
48
|
+
.ruff_cache/
|
|
49
|
+
python/dist/
|
|
50
|
+
python/build/
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Serhatcck
|
|
4
|
+
Copyright (c) 2026 FlyPhantomFly
|
|
5
|
+
Copyright (c) 2026 mobile-security-mcp contributors (Python server)
|
|
6
|
+
|
|
7
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
8
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
9
|
+
in the Software without restriction, including without limitation the rights
|
|
10
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
11
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
12
|
+
furnished to do so, subject to the following conditions:
|
|
13
|
+
|
|
14
|
+
The above copyright notice and this permission notice shall be included in all
|
|
15
|
+
copies or substantial portions of the Software.
|
|
16
|
+
|
|
17
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
18
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
19
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
20
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
21
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
22
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
23
|
+
SOFTWARE.
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
# Notice
|
|
2
|
+
The Python server in this package is derived from `mobile-security-mcp` 0.1.4 on PyPI (MIT, by "mobile-security-mcp contributors"). Its public repository could not be found, so the source used here is the published 0.1.4 package. The original declares the MIT license but ships no license file or named copyright holder. The MIT notice is kept in `LICENSE` and the original contributors are credited there.
|
|
3
|
+
Changes from 0.1.4: renamed to `mobile-re-mcp` (rebranded again to `android-re-mcp` in 1.4.0, see CHANGELOG), argument checks on every tool call, radare2 and ripgrep injection fixes, loopback-only SSE with a token for anything else, loopback-only mitmproxy, private scratch folders instead of `/tmp`, SHA-256 pinned downloads, notes stored in the user data folder, `install_tool` off by default, and the SDK pinned below 2.0.
|
|
4
|
+
This project is not affiliated with or endorsed by the original authors.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: android-re-mcp
|
|
3
|
+
Version: 1.4.0
|
|
4
|
+
Summary: Android dynamic analysis MCP server: adb, Frida, mitmproxy, apktool, jadx
|
|
5
|
+
Project-URL: Homepage, https://github.com/FlyPhantomFly/android-re-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/FlyPhantomFly/android-re-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/FlyPhantomFly/android-re-mcp/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/FlyPhantomFly/android-re-mcp/blob/master/CHANGELOG.md
|
|
9
|
+
Author: FlyPhantomFly, mobile-security-mcp contributors
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
License-File: NOTICE.md
|
|
13
|
+
Keywords: adb,android,apktool,frida,mcp,mitmproxy,mobile-security,model-context-protocol,pentest,reverse-engineering
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Information Technology
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Security
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Requires-Dist: mcp<2,>=1.30
|
|
23
|
+
Provides-Extra: all
|
|
24
|
+
Requires-Dist: androguard<5,>=4.0; extra == 'all'
|
|
25
|
+
Requires-Dist: apkid>=2.1.0; extra == 'all'
|
|
26
|
+
Requires-Dist: apkleaks>=2.6.0; extra == 'all'
|
|
27
|
+
Requires-Dist: frida-tools>=12.0.0; extra == 'all'
|
|
28
|
+
Requires-Dist: frida>=16.0.0; extra == 'all'
|
|
29
|
+
Requires-Dist: mitmproxy>=10.0.0; extra == 'all'
|
|
30
|
+
Requires-Dist: quark-engine>=23.0.0; extra == 'all'
|
|
31
|
+
Provides-Extra: analysis
|
|
32
|
+
Requires-Dist: quark-engine>=23.0.0; extra == 'analysis'
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: androguard<5,>=4.0; extra == 'dev'
|
|
35
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
36
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
37
|
+
Provides-Extra: frida
|
|
38
|
+
Requires-Dist: frida-tools>=12.0.0; extra == 'frida'
|
|
39
|
+
Requires-Dist: frida>=16.0.0; extra == 'frida'
|
|
40
|
+
Provides-Extra: network
|
|
41
|
+
Requires-Dist: mitmproxy>=10.0.0; extra == 'network'
|
|
42
|
+
Provides-Extra: static
|
|
43
|
+
Requires-Dist: androguard<5,>=4.0; extra == 'static'
|
|
44
|
+
Requires-Dist: apkid>=2.1.0; extra == 'static'
|
|
45
|
+
Requires-Dist: apkleaks>=2.6.0; extra == 'static'
|
|
46
|
+
Description-Content-Type: text/markdown
|
|
47
|
+
|
|
48
|
+
# android-re-mcp (Python)
|
|
49
|
+
The live-device half of [android-re-mcp](https://github.com/FlyPhantomFly/android-re-mcp). It is an MCP server that lets an AI assistant drive adb, Frida, mitmproxy, apktool and jadx against a test phone: decompile an app, hook it, read its traffic, patch it, sign it and install it again.
|
|
50
|
+
The npm predecessor (`android-re-mcp`) is being retired — its static Android tools move into this package and its iOS tools are dropped (1.4.0). This package is the sole survivor.
|
|
51
|
+
|
|
52
|
+
## Install
|
|
53
|
+
```bash
|
|
54
|
+
pip install "android-re-mcp[all]"
|
|
55
|
+
android-re-mcp --setup
|
|
56
|
+
```
|
|
57
|
+
It needs Python 3.11 or newer. The base install is just the MCP server. The `[all]` extra adds Frida, androguard, apkid, apkleaks, mitmproxy and quark-engine, and you can pick parts instead: `frida`, `static`, `network`, `analysis`. If Frida is already pinned in your environment, install without extras and the server will not touch it.
|
|
58
|
+
`--setup` downloads pinned, checksum-verified copies of apktool, jadx, uber-apk-signer and Il2CppDumper into `~/tools`. adb comes from your package manager (`sudo apt install adb`).
|
|
59
|
+
|
|
60
|
+
## Connect it
|
|
61
|
+
Claude Code:
|
|
62
|
+
```bash
|
|
63
|
+
claude mcp add android-re -- android-re-mcp
|
|
64
|
+
```
|
|
65
|
+
opencode, in `~/.config/opencode/opencode.json`:
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"mcp": {
|
|
69
|
+
"android-re": { "type": "local", "command": ["/path/to/venv/bin/android-re-mcp"], "enabled": true }
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
Use the full path to the command if it lives in a virtualenv. Any other client needs only the command, with no arguments.
|
|
74
|
+
Start with a check of what is installed. Ask "Run check_tools", and the assistant lists which tools it found and which are missing.
|
|
75
|
+
|
|
76
|
+
## A first session
|
|
77
|
+
Ask in plain language and the assistant picks the tools. Some prompts and what they use:
|
|
78
|
+
- "List my devices, then push frida-server to the phone and start it." (`adb_devices`, `frida_server_push`)
|
|
79
|
+
- "Decompile /home/me/apks/app.apk and search the strings for token or secret." (`apk_decompile`, `search_strings`)
|
|
80
|
+
- "Which protection does com.example.app use, and how do I get past it?" (`rasp_identify`, `rasp_bypass`)
|
|
81
|
+
- "Start mitmproxy, open the app on the phone, then show me the requests it made." (`mitm_start`, `mitm_read_flows`)
|
|
82
|
+
- "Patch the license check in the smali, rebuild, sign and install it." (`smali_patch`, `apk_rebuild_sign`, `adb_install`)
|
|
83
|
+
- "Dump the app's memory and look for the session key." (`frida_memdump`, `frida_find_bytes`)
|
|
84
|
+
|
|
85
|
+
The server also carries short playbooks as MCP prompts, and it keeps per-app notes (`memory_read`, `memory_write`) so a later session can pick up where the last one stopped.
|
|
86
|
+
|
|
87
|
+
## What is in it
|
|
88
|
+
| Group | Tools | Needs |
|
|
89
|
+
| --- | --- | --- |
|
|
90
|
+
| Static | `apk_decompile`, `apk_identify`, `apk_scan_secrets`, `manifest_parse`, `search_strings`, `find_urls`, `find_crypto_usage` | apktool, jadx, ripgrep, apkid |
|
|
91
|
+
| Frida | `frida_spawn`, `frida_attach`, `frida_inject`, `frida_memdump`, `objection_run` | Frida, a rooted phone or a gadget |
|
|
92
|
+
| Device | `adb_devices`, `adb_shell`, `adb_install`, `adb_pull`, `adb_push`, `adb_logcat_*`, `scrcpy_*` | adb, scrcpy |
|
|
93
|
+
| Network | `mitm_start`, `mitm_stop`, `mitm_read_flows`, `mitm_export_har`, `ssl_kill_switch` | mitmproxy |
|
|
94
|
+
| Patching | `smali_patch`, `inject_gadget`, `apk_sign`, `apk_rebuild_sign` | apktool, uber-apk-signer, Java |
|
|
95
|
+
| Native and cross-platform | `native_strings`, `native_exports`, `native_disasm`, `il2cpp_dump`, `blutter_extract`, `hermes_decode` | radare2, Il2CppDumper, Blutter |
|
|
96
|
+
| Protections | `rasp_identify`, `rasp_bypass` | none |
|
|
97
|
+
|
|
98
|
+
The Frida script library behind `frida_list_scripts` is empty until you add scripts of your own to `~/.local/share/android-re-mcp/frida_scripts`. The bypass scripts in `rasp_bypass` are built in.
|
|
99
|
+
|
|
100
|
+
## Staying safe
|
|
101
|
+
This server can run commands on your phone and your computer, so treat its tools with care.
|
|
102
|
+
- Use stdio. `--transport sse` listens on 127.0.0.1 only, and any other `--host` needs `ANDROID_RE_MCP_TOKEN`, which clients send as a bearer token.
|
|
103
|
+
- Set `ANDROID_RE_MCP_ALLOWED_DIRS` (folders separated by `:`) to keep file arguments inside your workspace. Paths under `~/.ssh`, `~/.config/gh`, shell rc files and similar are always refused.
|
|
104
|
+
- Switch tools off with `ANDROID_RE_MCP_DISABLE_TOOLS=adb_shell,adb_push,adb_pull`, and set the risky ones to ask first in your client.
|
|
105
|
+
- `install_tool` is off unless you set `ANDROID_RE_MCP_ALLOW_INSTALL=1`. `--setup` always works because you run it yourself.
|
|
106
|
+
- mitmproxy listens on 127.0.0.1. Run `adb reverse tcp:8080 tcp:8080` and point the phone's proxy at 127.0.0.1:8080.
|
|
107
|
+
- A sample you analyze can try to steer the assistant through its own strings and symbol names. Use a VM, and do not auto-approve tools that touch the device.
|
|
108
|
+
|
|
109
|
+
## Files
|
|
110
|
+
Notes, captures and scratch files live in `~/.local/share/android-re-mcp` (set `ANDROID_RE_MCP_HOME` to move them). Settings such as your signing keystore go in `~/.config/android-re-mcp/config.toml`. Downloaded tools go in `~/tools`.
|
|
111
|
+
|
|
112
|
+
## Credits
|
|
113
|
+
Derived from `mobile-security-mcp` 0.1.4 on PyPI (MIT), whose authors are not named. See [NOTICE.md](NOTICE.md). MIT licensed.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# android-re-mcp (Python)
|
|
2
|
+
The live-device half of [android-re-mcp](https://github.com/FlyPhantomFly/android-re-mcp). It is an MCP server that lets an AI assistant drive adb, Frida, mitmproxy, apktool and jadx against a test phone: decompile an app, hook it, read its traffic, patch it, sign it and install it again.
|
|
3
|
+
The npm predecessor (`android-re-mcp`) is being retired — its static Android tools move into this package and its iOS tools are dropped (1.4.0). This package is the sole survivor.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
```bash
|
|
7
|
+
pip install "android-re-mcp[all]"
|
|
8
|
+
android-re-mcp --setup
|
|
9
|
+
```
|
|
10
|
+
It needs Python 3.11 or newer. The base install is just the MCP server. The `[all]` extra adds Frida, androguard, apkid, apkleaks, mitmproxy and quark-engine, and you can pick parts instead: `frida`, `static`, `network`, `analysis`. If Frida is already pinned in your environment, install without extras and the server will not touch it.
|
|
11
|
+
`--setup` downloads pinned, checksum-verified copies of apktool, jadx, uber-apk-signer and Il2CppDumper into `~/tools`. adb comes from your package manager (`sudo apt install adb`).
|
|
12
|
+
|
|
13
|
+
## Connect it
|
|
14
|
+
Claude Code:
|
|
15
|
+
```bash
|
|
16
|
+
claude mcp add android-re -- android-re-mcp
|
|
17
|
+
```
|
|
18
|
+
opencode, in `~/.config/opencode/opencode.json`:
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"mcp": {
|
|
22
|
+
"android-re": { "type": "local", "command": ["/path/to/venv/bin/android-re-mcp"], "enabled": true }
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
Use the full path to the command if it lives in a virtualenv. Any other client needs only the command, with no arguments.
|
|
27
|
+
Start with a check of what is installed. Ask "Run check_tools", and the assistant lists which tools it found and which are missing.
|
|
28
|
+
|
|
29
|
+
## A first session
|
|
30
|
+
Ask in plain language and the assistant picks the tools. Some prompts and what they use:
|
|
31
|
+
- "List my devices, then push frida-server to the phone and start it." (`adb_devices`, `frida_server_push`)
|
|
32
|
+
- "Decompile /home/me/apks/app.apk and search the strings for token or secret." (`apk_decompile`, `search_strings`)
|
|
33
|
+
- "Which protection does com.example.app use, and how do I get past it?" (`rasp_identify`, `rasp_bypass`)
|
|
34
|
+
- "Start mitmproxy, open the app on the phone, then show me the requests it made." (`mitm_start`, `mitm_read_flows`)
|
|
35
|
+
- "Patch the license check in the smali, rebuild, sign and install it." (`smali_patch`, `apk_rebuild_sign`, `adb_install`)
|
|
36
|
+
- "Dump the app's memory and look for the session key." (`frida_memdump`, `frida_find_bytes`)
|
|
37
|
+
|
|
38
|
+
The server also carries short playbooks as MCP prompts, and it keeps per-app notes (`memory_read`, `memory_write`) so a later session can pick up where the last one stopped.
|
|
39
|
+
|
|
40
|
+
## What is in it
|
|
41
|
+
| Group | Tools | Needs |
|
|
42
|
+
| --- | --- | --- |
|
|
43
|
+
| Static | `apk_decompile`, `apk_identify`, `apk_scan_secrets`, `manifest_parse`, `search_strings`, `find_urls`, `find_crypto_usage` | apktool, jadx, ripgrep, apkid |
|
|
44
|
+
| Frida | `frida_spawn`, `frida_attach`, `frida_inject`, `frida_memdump`, `objection_run` | Frida, a rooted phone or a gadget |
|
|
45
|
+
| Device | `adb_devices`, `adb_shell`, `adb_install`, `adb_pull`, `adb_push`, `adb_logcat_*`, `scrcpy_*` | adb, scrcpy |
|
|
46
|
+
| Network | `mitm_start`, `mitm_stop`, `mitm_read_flows`, `mitm_export_har`, `ssl_kill_switch` | mitmproxy |
|
|
47
|
+
| Patching | `smali_patch`, `inject_gadget`, `apk_sign`, `apk_rebuild_sign` | apktool, uber-apk-signer, Java |
|
|
48
|
+
| Native and cross-platform | `native_strings`, `native_exports`, `native_disasm`, `il2cpp_dump`, `blutter_extract`, `hermes_decode` | radare2, Il2CppDumper, Blutter |
|
|
49
|
+
| Protections | `rasp_identify`, `rasp_bypass` | none |
|
|
50
|
+
|
|
51
|
+
The Frida script library behind `frida_list_scripts` is empty until you add scripts of your own to `~/.local/share/android-re-mcp/frida_scripts`. The bypass scripts in `rasp_bypass` are built in.
|
|
52
|
+
|
|
53
|
+
## Staying safe
|
|
54
|
+
This server can run commands on your phone and your computer, so treat its tools with care.
|
|
55
|
+
- Use stdio. `--transport sse` listens on 127.0.0.1 only, and any other `--host` needs `ANDROID_RE_MCP_TOKEN`, which clients send as a bearer token.
|
|
56
|
+
- Set `ANDROID_RE_MCP_ALLOWED_DIRS` (folders separated by `:`) to keep file arguments inside your workspace. Paths under `~/.ssh`, `~/.config/gh`, shell rc files and similar are always refused.
|
|
57
|
+
- Switch tools off with `ANDROID_RE_MCP_DISABLE_TOOLS=adb_shell,adb_push,adb_pull`, and set the risky ones to ask first in your client.
|
|
58
|
+
- `install_tool` is off unless you set `ANDROID_RE_MCP_ALLOW_INSTALL=1`. `--setup` always works because you run it yourself.
|
|
59
|
+
- mitmproxy listens on 127.0.0.1. Run `adb reverse tcp:8080 tcp:8080` and point the phone's proxy at 127.0.0.1:8080.
|
|
60
|
+
- A sample you analyze can try to steer the assistant through its own strings and symbol names. Use a VM, and do not auto-approve tools that touch the device.
|
|
61
|
+
|
|
62
|
+
## Files
|
|
63
|
+
Notes, captures and scratch files live in `~/.local/share/android-re-mcp` (set `ANDROID_RE_MCP_HOME` to move them). Settings such as your signing keystore go in `~/.config/android-re-mcp/config.toml`. Downloaded tools go in `~/tools`.
|
|
64
|
+
|
|
65
|
+
## Credits
|
|
66
|
+
Derived from `mobile-security-mcp` 0.1.4 on PyPI (MIT), whose authors are not named. See [NOTICE.md](NOTICE.md). MIT licensed.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "android-re-mcp"
|
|
7
|
+
version = "1.4.0"
|
|
8
|
+
description = "Android dynamic analysis MCP server: adb, Frida, mitmproxy, apktool, jadx"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.11"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE", "NOTICE.md"]
|
|
13
|
+
authors = [{ name = "FlyPhantomFly" }, { name = "mobile-security-mcp contributors" }]
|
|
14
|
+
keywords = ["mcp", "model-context-protocol", "android", "frida", "mobile-security", "reverse-engineering", "pentest", "adb", "apktool", "mitmproxy"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"Intended Audience :: Information Technology",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3.11",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Topic :: Security",
|
|
23
|
+
]
|
|
24
|
+
dependencies = ["mcp>=1.30,<2"]
|
|
25
|
+
|
|
26
|
+
[project.optional-dependencies]
|
|
27
|
+
frida = ["frida>=16.0.0", "frida-tools>=12.0.0"]
|
|
28
|
+
static = ["androguard>=4.0,<5", "apkid>=2.1.0", "apkleaks>=2.6.0"]
|
|
29
|
+
network = ["mitmproxy>=10.0.0"]
|
|
30
|
+
analysis = ["quark-engine>=23.0.0"]
|
|
31
|
+
all = ["android-re-mcp[frida,static,network,analysis]"]
|
|
32
|
+
dev = ["pytest>=8", "ruff>=0.6", "androguard>=4.0,<5"]
|
|
33
|
+
|
|
34
|
+
[project.scripts]
|
|
35
|
+
android-re-mcp = "android_re_mcp.__main__:main"
|
|
36
|
+
|
|
37
|
+
[project.urls]
|
|
38
|
+
Homepage = "https://github.com/FlyPhantomFly/android-re-mcp"
|
|
39
|
+
Repository = "https://github.com/FlyPhantomFly/android-re-mcp"
|
|
40
|
+
Issues = "https://github.com/FlyPhantomFly/android-re-mcp/issues"
|
|
41
|
+
Changelog = "https://github.com/FlyPhantomFly/android-re-mcp/blob/master/CHANGELOG.md"
|
|
42
|
+
|
|
43
|
+
[tool.hatch.build.targets.wheel]
|
|
44
|
+
packages = ["src/android_re_mcp"]
|
|
45
|
+
|
|
46
|
+
[tool.hatch.build.targets.sdist]
|
|
47
|
+
include = ["src", "tests", "README.md", "LICENSE", "NOTICE.md", "pyproject.toml"]
|
|
48
|
+
|
|
49
|
+
[tool.pytest.ini_options]
|
|
50
|
+
testpaths = ["tests"]
|
|
51
|
+
|
|
52
|
+
[tool.ruff]
|
|
53
|
+
line-length = 120
|
|
54
|
+
target-version = "py311"
|
|
55
|
+
|
|
56
|
+
[tool.ruff.lint]
|
|
57
|
+
select = ["F", "E9", "B", "S102", "S307", "S602", "S605"]
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""android-re-mcp (Python): dynamic Android analysis MCP server.
|
|
2
|
+
|
|
3
|
+
Derived from mobile-security-mcp 0.1.4 (MIT). See NOTICE.md in the repository.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
7
|
+
|
|
8
|
+
try:
|
|
9
|
+
__version__ = version("android-re-mcp")
|
|
10
|
+
except PackageNotFoundError: # running from a source checkout
|
|
11
|
+
__version__ = "0+local"
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Entry point for the android-re-mcp MCP server.
|
|
3
|
+
|
|
4
|
+
Usage:
|
|
5
|
+
python -m android_re_mcp # stdio transport (default)
|
|
6
|
+
python -m android_re_mcp --transport sse --port 8765 # SSE, loopback only
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import argparse
|
|
12
|
+
import asyncio
|
|
13
|
+
import logging
|
|
14
|
+
import sys
|
|
15
|
+
|
|
16
|
+
logger = logging.getLogger(__name__)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def _build_parser() -> argparse.ArgumentParser:
|
|
20
|
+
p = argparse.ArgumentParser(
|
|
21
|
+
prog="android-re-mcp",
|
|
22
|
+
description="Android dynamic analysis MCP server (Python half of android-re-mcp)",
|
|
23
|
+
)
|
|
24
|
+
p.add_argument(
|
|
25
|
+
"--transport",
|
|
26
|
+
choices=["stdio", "sse"],
|
|
27
|
+
default="stdio",
|
|
28
|
+
help="Transport to use (default: stdio)",
|
|
29
|
+
)
|
|
30
|
+
p.add_argument(
|
|
31
|
+
"--host",
|
|
32
|
+
default="127.0.0.1",
|
|
33
|
+
help="Address for SSE transport (default: 127.0.0.1). Anything else needs ANDROID_RE_MCP_TOKEN.",
|
|
34
|
+
)
|
|
35
|
+
p.add_argument(
|
|
36
|
+
"--port",
|
|
37
|
+
type=int,
|
|
38
|
+
default=8765,
|
|
39
|
+
help="Port for SSE transport (default: 8765)",
|
|
40
|
+
)
|
|
41
|
+
p.add_argument(
|
|
42
|
+
"--log-level",
|
|
43
|
+
default="WARNING",
|
|
44
|
+
choices=["DEBUG", "INFO", "WARNING", "ERROR"],
|
|
45
|
+
)
|
|
46
|
+
p.add_argument(
|
|
47
|
+
"--setup",
|
|
48
|
+
action="store_true",
|
|
49
|
+
help="Automatically download and install all missing RE tools into ~/tools",
|
|
50
|
+
)
|
|
51
|
+
return p
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def main() -> None:
|
|
55
|
+
"""Main entry point — starts the MCP server."""
|
|
56
|
+
parser = _build_parser()
|
|
57
|
+
args = parser.parse_args()
|
|
58
|
+
|
|
59
|
+
logging.basicConfig(
|
|
60
|
+
level=getattr(logging, args.log_level),
|
|
61
|
+
format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
|
|
62
|
+
stream=sys.stderr,
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
if args.setup:
|
|
66
|
+
print("[*] Starting zero-touch automated setup...")
|
|
67
|
+
from android_re_mcp.setup.install_tool import install_all_missing_tools
|
|
68
|
+
install_all_missing_tools()
|
|
69
|
+
print("[*] Setup complete! You can now start the MCP server.")
|
|
70
|
+
sys.exit(0)
|
|
71
|
+
|
|
72
|
+
from android_re_mcp.paths import ensure_tools_on_path
|
|
73
|
+
|
|
74
|
+
ensure_tools_on_path()
|
|
75
|
+
|
|
76
|
+
# Import here so startup errors surface cleanly
|
|
77
|
+
from android_re_mcp.server import create_server
|
|
78
|
+
|
|
79
|
+
server = create_server()
|
|
80
|
+
|
|
81
|
+
if args.transport == "stdio":
|
|
82
|
+
logger.info("Starting android-re-mcp over stdio")
|
|
83
|
+
asyncio.run(server.run_stdio())
|
|
84
|
+
else:
|
|
85
|
+
logger.info("Starting android-re-mcp SSE on %s:%d", args.host, args.port)
|
|
86
|
+
asyncio.run(server.run_sse(host=args.host, port=args.port))
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
if __name__ == "__main__":
|
|
90
|
+
main()
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""Locate the CLI executables the handlers actually invoke.
|
|
2
|
+
|
|
3
|
+
PATH is checked first, then the console-script directory that lives next
|
|
4
|
+
to the running interpreter (venv installs), which PATH often misses when
|
|
5
|
+
the server is started from an unactivated virtualenv — exactly the case
|
|
6
|
+
where `pip show apkleaks` said available while the handler said
|
|
7
|
+
missing_tool.
|
|
8
|
+
|
|
9
|
+
check_tools and every handler resolve through this module, so what the
|
|
10
|
+
inventory reports is what the tools really execute.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import os
|
|
16
|
+
import shutil
|
|
17
|
+
import sys
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def find_cli(name: str) -> str | None:
|
|
22
|
+
"""Absolute path of *name* as the handlers would invoke it, or None."""
|
|
23
|
+
if not name or os.path.basename(name) != name:
|
|
24
|
+
# Only plain tool names are expected; anything else is a caller bug.
|
|
25
|
+
return None
|
|
26
|
+
hit = shutil.which(name)
|
|
27
|
+
if hit:
|
|
28
|
+
return hit
|
|
29
|
+
candidates: list[Path] = []
|
|
30
|
+
# NB: absolute(), not resolve() — a venv interpreter is usually a symlink;
|
|
31
|
+
# resolving it would leave the venv's script directory entirely.
|
|
32
|
+
candidates.append(Path(sys.executable).absolute().parent)
|
|
33
|
+
scripts_name = "Scripts" if os.name == "nt" else "bin"
|
|
34
|
+
candidates.append(Path(sys.prefix) / scripts_name)
|
|
35
|
+
suffixes = (".exe", ".cmd", ".bat", "") if os.name == "nt" else ("",)
|
|
36
|
+
seen: set[Path] = set()
|
|
37
|
+
for directory in candidates:
|
|
38
|
+
if directory in seen:
|
|
39
|
+
continue
|
|
40
|
+
seen.add(directory)
|
|
41
|
+
for suffix in suffixes:
|
|
42
|
+
candidate = directory / f"{name}{suffix}"
|
|
43
|
+
try:
|
|
44
|
+
if candidate.is_file() and os.access(candidate, os.X_OK):
|
|
45
|
+
return str(candidate)
|
|
46
|
+
except OSError: # pragma: no cover - defensive
|
|
47
|
+
continue
|
|
48
|
+
return None
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""Settings from the packaged defaults, overridden by the user's config file."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from android_re_mcp.paths import tools_dir, user_config_path
|
|
9
|
+
|
|
10
|
+
_DEFAULTS = Path(__file__).parent / "config.toml"
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def _read(path: Path) -> dict:
|
|
14
|
+
try:
|
|
15
|
+
import tomllib
|
|
16
|
+
except ImportError: # Python < 3.11 is not supported, kept for safety
|
|
17
|
+
return {}
|
|
18
|
+
try:
|
|
19
|
+
with open(path, "rb") as fh:
|
|
20
|
+
return tomllib.load(fh)
|
|
21
|
+
except (FileNotFoundError, PermissionError, ValueError):
|
|
22
|
+
return {}
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def load_config() -> dict[str, dict[str, Any]]:
|
|
26
|
+
merged = _read(_DEFAULTS)
|
|
27
|
+
for section, values in _read(user_config_path()).items():
|
|
28
|
+
if isinstance(values, dict):
|
|
29
|
+
merged.setdefault(section, {}).update(values)
|
|
30
|
+
return merged
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def signer_jar() -> Path:
|
|
34
|
+
"""Absolute path to uber-apk-signer. Never resolved against the working directory."""
|
|
35
|
+
configured = str(load_config().get("signing", {}).get("jar_path", "") or "")
|
|
36
|
+
if configured and Path(configured).is_absolute():
|
|
37
|
+
return Path(configured)
|
|
38
|
+
return tools_dir() / "signing" / "uber-apk-signer.jar"
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Defaults only. Put your own settings in ~/.config/android-re-mcp/config.toml (or $ANDROID_RE_MCP_CONFIG).
|
|
2
|
+
[signing]
|
|
3
|
+
# Absolute path to uber-apk-signer.jar. Empty uses ~/tools/signing/uber-apk-signer.jar
|
|
4
|
+
jar_path = ""
|
|
5
|
+
# Empty keystore uses uber-apk-signer's built-in debug keystore. Passwords given here show up in the process list.
|
|
6
|
+
keystore_path = ""
|
|
7
|
+
keystore_password = ""
|
|
8
|
+
key_alias = ""
|
|
9
|
+
key_password = ""
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Frida script library package — categorized JS scripts for Android RE."""
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Rebuild the frida_scripts/*.js bundles from the raw sources in src/.
|
|
3
|
+
#
|
|
4
|
+
# frida 17 removed the global `Java`/`ObjC` bridges from script runtimes
|
|
5
|
+
# (QuickJS *and* V8): scripts must import them explicitly. Raw sources
|
|
6
|
+
# are written against the classic global and cannot work as-is, so every
|
|
7
|
+
# Java-hooking script ships as a self-contained bundle with
|
|
8
|
+
# frida-java-bridge compiled in. memory_scan is pure-native and ships as
|
|
9
|
+
# the raw source.
|
|
10
|
+
#
|
|
11
|
+
# Prerequisites: node + frida-compile (pipx-installed frida-tools ships
|
|
12
|
+
# it) and a checkout of the bridge: `npm install frida-java-bridge`.
|
|
13
|
+
#
|
|
14
|
+
# Usage: cd python/src/android_re_mcp/frida_scripts && bash build_bundles.sh
|
|
15
|
+
set -euo pipefail
|
|
16
|
+
|
|
17
|
+
HERE="$(cd "$(dirname "$0")" && pwd)"
|
|
18
|
+
COMPILE="${FRIDA_COMPILE:-$(command -v frida-compile || echo /home/dragon/.local/bin/frida-compile)}"
|
|
19
|
+
|
|
20
|
+
WORK="$(mktemp -d)"
|
|
21
|
+
trap 'rm -rf "$WORK"' EXIT
|
|
22
|
+
|
|
23
|
+
cd "$WORK"
|
|
24
|
+
# The bridge must resolve from the working directory.
|
|
25
|
+
if [ ! -d node_modules/frida-java-bridge ]; then
|
|
26
|
+
echo "[*] Installing frida-java-bridge..."
|
|
27
|
+
npm init -y >/dev/null
|
|
28
|
+
npm install frida-java-bridge >/dev/null 2>&1
|
|
29
|
+
fi
|
|
30
|
+
|
|
31
|
+
for f in "$HERE"/src/*.js; do
|
|
32
|
+
name="$(basename "$f" .js)"
|
|
33
|
+
if [ "$name" = "memory_scan" ]; then
|
|
34
|
+
continue # pure-native: ships as-is
|
|
35
|
+
fi
|
|
36
|
+
{
|
|
37
|
+
echo 'import Java from "frida-java-bridge";'
|
|
38
|
+
cat "$f"
|
|
39
|
+
} > "$name.entry.js"
|
|
40
|
+
"$COMPILE" -S -B iife "$name.entry.js" -o "$HERE/$name.js"
|
|
41
|
+
node --check "$HERE/$name.js"
|
|
42
|
+
echo "[+] bundled $name ($(wc -c < "$HERE/$name.js") bytes)"
|
|
43
|
+
done
|
|
44
|
+
|
|
45
|
+
echo "[*] Verifying config-protocol and bridge markers..."
|
|
46
|
+
for out in "$HERE"/*.js; do
|
|
47
|
+
name="$(basename "$out" .js)"
|
|
48
|
+
[ "$name" = "memory_scan" ] && continue
|
|
49
|
+
n_recv=$(grep -c 'recv("config"' "$out" || true)
|
|
50
|
+
n_bridge=$(grep -c "frida-java-bridge" "$out" || true)
|
|
51
|
+
if [ "$n_recv" -lt 2 ] || [ "$n_bridge" -lt 1 ]; then
|
|
52
|
+
echo "[!] $name: recv=$n_recv bridge=$n_bridge — refusing" >&2
|
|
53
|
+
exit 1
|
|
54
|
+
fi
|
|
55
|
+
done
|
|
56
|
+
echo "[*] All bundles verified."
|