android-renef-mcp
An MCP server for Renef, a Frida-like dynamic instrumentation toolkit for Android ARM64. With it, an AI agent can attach to a process on a rooted device (or spawn one, held paused at startup), run Lua inside the target, hook native and Java methods, read and write process memory, and collect hook output.
Renef is not Frida: the agent runs Lua instead of JavaScript, the API is its own
(hook(), Module.*, Memory.*, Java.use, Syscall.trace), and nothing
frida-related has to be on the device. Just renef_server and a rooted handset.
That matters for apps whose protections look for Frida.
┌──────────────┐ stdio/MCP ┌─────────────┐ TCP :1907 ┌───────────────┐
│ MCP client │ ◄───────────► │ renef-mcp │ ◄──────────► │ renef_server │
│ (AI agent) │ │ (this pkg) │ (adb fwd) │ on device(adb)│
└──────────────┘ └─────────────┘ └──────┬────────┘
│ agent socket
▼
┌─────────────────┐
│ libagent.so │
│ inside target │
│ app (Lua VM) │
└─────────────────┘
Differences from renef-mcp
There is already an MCP server for Renef:
ahmeth4n/renef-mcp on PyPI (that's also
where the name renef-mcp is taken). This package exists because its core is
built differently, and after running both against a real device, differently in
ways that matter:
| android-renef-mcp (this package) | renef-mcp (ahmeth4n, 0.3.0) | |
|---|---|---|
| Talking to the device | Speaks the renef_server TCP protocol directly, over an adb forward |
Launches the desktop renef CLI as a subprocess and scrapes its renef> prompt |
| Multi-line Lua | Native, sent in one write | Broken; needs a second hex-encoding tool as a workaround |
| Response framing | Every exec carries a nonce marker, runs exactly once, and times out loudly | Blind waits for the prompt; a hook firing mid-response bleeds into the next tool's output |
| Spawn | Real startup gating (ptrace pause), first exec resumes it | Sends the legacy --hook= flag the server strips and ignores |
| Memory search | 'DEADBEEF' searches those bytes; spaced and wildcard patterns validated |
'DEADBEEF' searches the ASCII text of that string — a silent wrong answer |
| Native hooks | Lua callbacks (onEnter/onLeave), PLT/GOT via caller= |
The hookn command, which installs no callbacks |
| Tests | 45-check end-to-end suite over real MCP stdio | None |
Upstream also ships ~9.5 MB of prebuilt host binaries and runs on Linux/macOS only; this package is ~100 KB of Python and runs anywhere Python and adb do.
Credit where due: the server lifecycle tools, framework detection, the Lua script library and the SSL-pinning knowledge base here are adapted from upstream's work (MIT, credited in their sections below).
Tools (38)
Status and discovery (no target needed)
renef_status()— adb devices, port forward, server ping/pong, session staterenef_list_apps(third_party_only)— installed packagesrenef_list_processes()— running processes, forrenef_attach
Server lifecycle (no session needed)
renef_server_deploy(source)— pushrenef_server+libagent.soto the device, set permissions and the SELinux context the agent needs, verify by md5. With the defaultsource="auto"it prefers a local Renef build and otherwise downloads the pinned, CI-built binaries (SHA-verified) — no NDK requiredrenef_server_start()/renef_server_stop()/renef_server_restart()— root-managed lifecycle with ping verificationrenef_server_logs(lines)— tail the server log on the device
Session
renef_attach(pid)— inject the agent into a running processrenef_spawn(package)— spawn an app gated at startup (ptrace pause) and inject the agent. The first exec auto-resumes it, or callrenef_resumewithout a scriptrenef_resume()— resume a spawn-gated processrenef_disconnect()— close the session; the target keeps running
Execution
renef_exec(lua)— run Lua in the target and get back itsprint()output. The workhorse, and multi-line Lua is finerenef_load_script(path)— run a Lua file from the host machine
Memory
renef_mem_scan(pattern, module)— scan for a hex pattern. Prefermodule="libfoo.so", which uses LuaMemory.searchand takes spaces and??wildcards. Without a module it's the upstream full-process scan: compact hex only, and big processes can outrun the server's ~10s response caprenef_mem_read(addr, size)— hexdump, up to 4096 bytesrenef_mem_read_value(addr, size, signed)— integer read, 1/2/4/8 bytesrenef_mem_read_string(addr, max_len)— NUL-terminated C stringrenef_mem_write(addr, hex_bytes)— write raw bytesrenef_mem_write_value(addr, value, size)— write an integer, verified by reading it backrenef_mem_patch(addr, hex_bytes)— likemem_writebut viaMemory.patch, which handlesmprotectitself, so read-only code pages are fair game
Modules
renef_module_list()andrenef_module_find(name)— loaded libraries, base addressesrenef_module_exports(name, filter, limit)/renef_module_symbols(name, filter, limit)renef_sections(lib)— ELF sections of a loaded libraryrenef_framework_detect()— flags Flutter, React Native, Unity, Xamarin or Cordova by their characteristic librariesrenef_hook_generate(lib, symbol_or_offset)— server-generated Lua hook template; give it a symbol and it resolves the offset first
Hooks
renef_hook_native(lib, offset, on_enter, on_leave, caller)— trampoline hook by default; passcaller="libtarget.so"for the PLT/GOT backend. Callbacks are Lua statements overargs[0..7](onEnter) andretval(onLeave). Find offsets withrenef_module_exportsfirstrenef_hook_java(class, method, signature, on_enter, on_leave)— ART method hook. Classes in slash form (com/example/Class), JNI signatures.args[0]is the ArtMethod pointer,args[1]isthis,args[2..]are the parameters, andargs.skip = truebypasses a void methodrenef_list_hooks()/renef_unhook(hook_id | "all")— native hooks only. Java hooks aren't in the upstream registry; they're cleared on the next attach/spawnrenef_watch(seconds)— capture hook/strace output for a window. Blocks the session exclusively, capped at 60s, and shows nothing if the app does nothing
Diagnostics
renef_backtrace()— current-thread call stack
Script library (vendored from ahmeth4n/renef-mcp, MIT)
renef_list_scripts()— 18 bundled examples: hook demos, tracing, and working bypasses likeflutter_ssl,ssl_unpinandroot_bypassrenef_get_script(name)— the Lua source, ready forrenef_load_script
Technique knowledge base (vendored from ahmeth4n/renef-mcp, MIT)
renef_technique_list()— categories and platforms; currentlyssl_pinningfor android_native, flutter, react_native, unity, xamarin and cordova_ionicrenef_technique(category, platform)— the assembled guide, e.g.renef_technique("ssl_pinning", "flutter")
Resources: renef://status for live chain status, renef://docs/lua-api for the
full Lua API reference (read from the Renef checkout). There's also a
renef_expert(task) prompt that keeps agents from accidentally writing Frida
code.
Usage
Requirements: Python 3.10+, adb, and a rooted ARM64 device. The Renef binaries
themselves you have two ways to get:
- No build needed.
renef_server_deploy()downloadsrenef_serverandlibagent.sothat CI builds from the pinned renef source (seerenef_mcp/BINARIES_PIN), SHA-verified against the release's checksums, and caches them under~/.cache/android-renef-mcp/. - Build your own. If you want binaries from your own checkout (useful while hacking on Renef itself):
cd ~/github/renef
make # produces build/android/renef_server and libagent.so
Then install this package and register it with your MCP client. Once it's on PyPI this is just:
pip install android-renef-mcp
claude mcp add renef -- android-renef-mcp
From a source checkout meanwhile:
cd ~/github/android-renef-mcp
uv sync
claude mcp add renef -- uv run --directory ~/github/android-renef-mcp android-renef-mcp
Or the JSON form most clients accept:
{
"mcpServers": {
"renef": {
"command": "uv",
"args": ["run", "--directory", "/home/<you>/github/android-renef-mcp", "android-renef-mcp"]
}
}
}
After that you don't need to touch adb yourself: renef_server_deploy() gets
the binaries (downloaded or local) onto the device, renef_server_start()
starts the server as root and sets up the port forward, and renef_status()
confirms the chain. If you'd rather do it
by hand, the old route still works:
adb shell "su -c '/data/local/tmp/renef_server'" # start the server (root)
The server takes no arguments. Environment variables, should you need them:
RENEF_HOME (Renef checkout, used for the Lua API docs resource; default
~/github/renef), RENEF_BIN_DIR (where renef_server_deploy finds the built
binaries; default <RENEF_HOME>/build/android), RENEF_HOST/RENEF_PORT
(server address, default 127.0.0.1:1907 over the adb forward) and RENEF_ADB
(adb binary path).
A session then looks like this:
renef_status
renef_spawn("com.example.app")
renef_module_exports("libtarget.so", filter="crypt")
renef_hook_native("libtarget.so", "0x1a2b3",
on_enter="print('arg:', Memory.readString(args[0]))")
renef_watch(5)
renef_unhook("all")
renef_disconnect()
Planned integration
This server is planned for integration into android-re-mcp as its Frida-alternative dynamic instrumentation layer. Until then, this repo is the standalone source.
License
Apache-2.0, © 2026 FlyPhantomFly. The bundled Lua scripts and technique
documents come from ahmeth4n/renef-mcp
and are MIT (© 2025 Byteria; license texts live in renef_mcp/scripts/ and
renef_mcp/techniques/).
Metadata
Release files for android-renef-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| android_renef_mcp-0.1.1.tar.gz | 147.3 kB | With provenance | Details for android_renef_mcp-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| android_renef_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for android_renef_mcp-0.1.1-py3-none-any.whl |
Total release size: 245.8 kB
Release files / android_renef_mcp-0.1.1.tar.gz
| Download URL | android_renef_mcp-0.1.1.tar.gz |
|---|---|
| Size | 147.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4a9b319795522b7bc7682914e46c4475291f2b9cbaf7dc860e5f07ee4813ee83
|
|
BLAKE2b-256 checksum How to use checksums |
9a6a82f6ee7e7e68d2983d00644ecdda9d47201bdbc889df7e2908970dd83ada
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / android_renef_mcp-0.1.1-py3-none-any.whl
| Download URL | android_renef_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 98.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
411fd1bd96b62dcff68d86d0fc0281853f677348d9e9b496e298c2c3a6432602
|
|
BLAKE2b-256 checksum How to use checksums |
a89a0da0a7744a965831b68ab22dc2c5afcbf28cde825c1142bbe56cc49955ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for android-renef-mcp 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for android_renef_mcp-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.