android-renef-mcp
Provides dynamic instrumentation for Android ARM64 apps via Renef, including attaching to or spawning processes, running Lua in the target, hooking Java and native methods, reading/writing process memory, inspecting modules, and managing hooks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@android-renef-mcp spawn com.example.app paused and hook SSL_read to log the plaintext"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 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 the renef_server and a rooted phone.
┌──────────────┐ 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. 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 | Launches the desktop |
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 |
Memory search |
|
|
Native hooks | Lua callbacks ( | The |
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).
Related MCP server: renef-mcp
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):
git clone https://github.com/FlyPhantomFly/android-renef-mcp
cd android-renef-mcp
make # produces build/android/renef_server and libagent.soThen install this package and register it with your MCP client. Once it's on PyPI this is just:
pip install android-renef-mcpclaude mcp add renef -- android-renef-mcpFrom a source checkout meanwhile:
git clone https://github.com/FlyPhantomFly/android-renef-mcp
cd android-renef-mcp
uv sync
claude mcp add renef -- uv run --directory ~/github/android-renef-mcp android-renef-mcpOr the JSON form most clients accept:
{
"mcpServers": {
"renef": {
"command": "uv",
"args": ["run", "--directory", "/home/<you>/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/).
Available Tools
38 toolsrenef_attachC
Attach to a running process and inject the renef agent.
Inputs: pid (required). Returns: result
renef_backtraceA
Print the current thread call stack in the target process (useful inside hook debugging).
Inputs: no named parameters. Returns: result
renef_disconnectA
Close the current target session (does not kill the target process).
Inputs: no named parameters. Returns: result
renef_execA
Execute Lua code in the target process and return print() output. Main tool. Examples: "print(Module.list())", "print(Memory.readString(args[0]))". Multi-line Lua is fine. See resource renef://docs/lua-api for the full API.
Inputs: lua (required). Returns: result
renef_framework_detectA
Detect the app framework (Flutter, React Native, Unity, Xamarin, Cordova/Ionic) by checking for its characteristic libraries. Needs a session.
Inputs: no named parameters. Returns: result
renef_get_scriptA
Return the Lua source of a bundled script (see renef_list_scripts), e.g. renef_get_script("flutter_ssl").
Inputs: name (required). Returns: result
renef_hook_generateB
Generate a ready-to-run Lua hook template (upstream hookgen command).
With a symbol it resolves the offset first (needs a session):
renef_hook_generate("libc.so", "fopen") or renef_hook_generate("libc.so", "0x1a2b3").
Inputs: lib (required), symbol_or_offset. Returns: result
renef_hook_javaA
Install a Java method hook. class_name in JNI slash format (e.g. "com/example/Class"), signature in JNI format (e.g. "(Ljava/lang/String;)Z"). arg layout: args[0]=ArtMethod* (ignore), args[1]=this (instance methods), args[2..]=parameters. Use on_enter="args.skip = true" to bypass void methods. Wrap uncertain classes in pcall via renef_exec.
Inputs: method (required), signature (required), class_name (required), on_enter, +1 more. Returns: result
renef_hook_nativeA
Install a native hook at offset (from library base) in lib, e.g. renef_hook_native("libc.so", "0x1234", on_enter="print('fopen path:', Memory.readString(args[0]))"). Callbacks are Lua statement strings using args[0..7] (onEnter) / retval (onLeave). Find offsets with renef_module_exports first. caller selects the upstream PLT/GOT backend (e.g. caller="libtarget.so"); omit it for a trampoline hook. There is no separate hook_type: upstream ignores the old --hook= argument and auto-selects from caller. WARNING: do not hook ultra-hot functions like clock_gettime/read/write - the agent's own output path may call them, causing recursive hooks that crash the target.
Inputs: lib (required), offset (required), caller, on_enter, +1 more. Returns: result
renef_list_appsA
List installed packages on the device (via adb, no session needed). Set third_party_only=true to skip system packages.
Inputs: third_party_only. Returns: result
renef_list_hooksA
List active native hooks in the target process. Upstream's registry is native-only: Java hooks (renef_hook_java) do not appear here and cannot be removed by renef_unhook; they are restored when the agent connection closes, i.e. on the next attach/spawn.
Inputs: no named parameters. Returns: result
renef_list_processesA
List running userland processes (pid + name) on the device, for renef_attach.
Inputs: no named parameters. Returns: result
renef_list_scriptsA
List the bundled Renef Lua example scripts (hook demos, tracing, flutter_ssl / ssl_unpin / root_bypass bypasses). Load one with renef_get_script
renef_load_script, or paste into renef_exec.
Inputs: no named parameters. Returns: result
renef_load_scriptC
Load a Lua script file from the MCP host machine and run it in the target.
Inputs: path (required). Returns: result
renef_mem_patchA
Write raw bytes to target memory using Memory.patch, which handles mprotect internally (works on read-only code pages that renef_mem_write cannot touch). hex_bytes: hex string, spaces allowed.
Inputs: addr (required), hex_bytes (required). Returns: result
renef_mem_readA
Read bytes from target memory and return a hexdump. addr accepts decimal or 0x-hex. size is capped at 4096 bytes.
Inputs: addr (required), size. Returns: result
renef_mem_read_stringC
Read a NUL-terminated C string from target memory.
Inputs: addr (required), max_len. Returns: result
renef_mem_read_valueB
Read an integer from target memory. size: 1, 2, 4 or 8 bytes (unsigned unless signed=true).
Inputs: addr (required), size, signed. Returns: result
renef_mem_scanA
Scan memory for a hex pattern. Prefer module="libfoo.so": it uses Lua Memory.search and supports spaces and ?? wildcards (e.g. "CA FE ?? BE"). Without module, the upstream full-process scan is used: compact hex only and it can exceed the server's ~10s response cap (an error will say so).
Inputs: pattern (required), module. Returns: result
renef_mem_writeC
Write raw bytes to target memory. hex_bytes: hex string, spaces allowed, e.g. "1F 20 03 D5".
Inputs: addr (required), hex_bytes (required). Returns: result
renef_mem_write_valueC
Write an integer to target memory. size: 1, 2, 4 or 8 bytes.
Inputs: addr (required), value (required), size. Returns: result
renef_module_exportsB
List exported symbols of a module. Use filter to substring-match names, limit to cap output.
Inputs: name (required), limit, filter. Returns: result
renef_module_findB
Get the base address of a loaded module, e.g. renef_module_find("libc.so").
Inputs: name (required). Returns: result
renef_module_listA
List loaded modules/libraries in the target process (base address, name, path).
Inputs: no named parameters. Returns: result
renef_module_symbolsB
List all symbols (including non-exported) of a module. filter/limit as in renef_module_exports.
Inputs: name (required), limit, filter. Returns: result
renef_resumeA
Resume a spawn-gated process (after renef_spawn).
Inputs: no named parameters. Returns: result
renef_sectionsC
List ELF sections of a loaded library (upstream sec command).
Inputs: lib (required). Returns: result
renef_server_deployA
Push the built renef_server + libagent.so to the device, set permissions and the SELinux context the agent needs, and verify by md5. source="auto" (default): prefer a local build (RENEF_BIN_DIR, else <RENEF_HOME>/build/android); if none exists, download the pinned CI-built binaries from this package's GitHub release and SHA256-verify them. source="build": require the local build. source="download": always download.
Inputs: source. Returns: result
renef_server_logsA
Tail the renef_server log from the device (last lines, default 60).
Inputs: lines. Returns: result
renef_server_restartA
Restart renef_server on the device (stop, then start with port forward).
Inputs: no named parameters. Returns: result
renef_server_startA
Start renef_server on the device as root (idempotent) and set up the adb port forward. Verifies with a ping.
Inputs: no named parameters. Returns: result
renef_server_stopA
Stop renef_server on the device (kill as root).
Inputs: no named parameters. Returns: result
renef_spawnA
Spawn an app by package name, gated at startup (ptrace pause), inject the agent. The first renef_exec auto-resumes the gated process; renef_resume resumes it without running a script.
Inputs: package (required). Returns: result
renef_statusA
Check the whole chain: adb device, adb port forward, renef_server reachability (ping/pong), and active target session. Start here.
Inputs: no named parameters. Returns: result
renef_techniqueB
Return the assembled technique guide for a platform, e.g. renef_technique("ssl_pinning", "flutter") or platform="react_native"/"unity"/"xamarin".
Inputs: category, platform. Returns: result
renef_technique_listA
List available technique knowledge bases and their platforms (e.g. ssl_pinning: android_native, flutter, react_native, unity, xamarin, cordova_ionic).
Inputs: no named parameters. Returns: result
renef_unhookA
Remove a hook by id (from renef_list_hooks), or "all" to remove every hook.
Inputs: hook_id (required). Returns: result
renef_watchA
Collect hook output for a time window (blocks, exclusive). Install hooks first (renef_hook_native / renef_hook_java), then call this to capture their prints. seconds capped at 60.
Inputs: seconds. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 38 tools
Most tools occupy clearly distinct niches: server lifecycle, session control, memory primitives, module inspection, hooking, and script/technique lookup are easy to separate, and descriptions explicitly flag the tricky pairs (mem_write vs mem_patch, module_exports vs module_symbols, list_hooks' native-only limitation). The main residual ambiguity is between overlapping memory-write/read helpers (mem_read vs mem_read_value vs mem_read_string, mem_write vs mem_patch), which are documented but still require the agent to read carefully. The exec/hook/watch family is well-differentiated.
Every tool carries the uniform `renef_` prefix and uses snake_case, so the set reads as one coherent namespace. Two ordering conventions coexist (resource_verb: mem_read, module_find, hook_native, technique_list vs verb_resource: list_apps, get_script, list_hooks), plus a bare noun (renef_sections), which is a minor deviation rather than a real inconsistency.
38 tools is well past the point where a single agent can hold the surface in working memory, and several are thin convenience wrappers (server_restart, mem_read_value, mem_read_string, module_find, backtrace) that arguably duplicate what renef_exec with inline Lua already provides. The domain is genuinely broad, but the surface could be consolidated substantially (e.g. a parameterized memory accessor instead of three read tools).
Lifecycle coverage is strong end-to-end: deploy/start/stop/logs, attach/spawn/resume/disconnect, memory scan/read/write/patch, module discovery, native and Java hooking, output capture, backtraces, and bundled script/technique libraries. Minor gaps remain — no thread enumeration, no register/context inspection, no Java class/method discovery tools (must be done via exec), and Java hooks cannot be listed or removed individually (documented as an upstream limitation).
Maintenance
Related MCP Connectors
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.
Cloud Android phones for AI agents: create a phone, read the screen, tap, type, install APKs, park.
Mobile sandboxes for AI agents: each agent gets its own cloud Android phone or iOS simulator over MCP, reads the screen, taps, types and installs your app. Android $0.01/min, iOS $0.03/min, parked phones free.
Related MCP Servers
- FlicenseAqualityFmaintenanceAn AI-driven Android dynamic analysis tool that enables AI models to perform automated reverse engineering by controlling Frida. It provides capabilities to inject scripts, manage application processes, and analyze real-time execution data through the Model Context Protocol.1070-
- AlicenseNot gradedqualityDmaintenanceMCP server for Renef, providing dynamic instrumentation and reverse engineering capabilities for Android ARM64, including native hooking, Java interception, and memory manipulation.9MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to see and control Android devices, with fast input, screenshots, UI element discovery, app and file management, shell access, and audio/video streaming or recording.468 npmMIT
- AlicenseCqualityBmaintenanceEnables AI agents to inspect APKs and resources, analyze native libraries, trace runtime behavior with Frida, and connect app screen actions to code through ADB.891MIT