android-renef-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| RENEF_ADB | No | Path to the adb binary. | |
| RENEF_HOME | No | Renef checkout directory, used for the Lua API docs resource (default: ~/github/renef). | ~/github/renef |
| RENEF_HOST | No | Server address host over the adb forward (default: 127.0.0.1). | 127.0.0.1 |
| RENEF_PORT | No | Server address port over the adb forward (default: 1907). | 1907 |
| RENEF_BIN_DIR | No | Where renef_server_deploy finds the built binaries (default: <RENEF_HOME>/build/android). | <RENEF_HOME>/build/android |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Renef MCP: dynamic instrumentation for Android ARM64 (Frida-like, Lua scripting). Workflow: renef_status -> renef_attach(pid) or renef_spawn(package) -> renef_exec(lua) / hook tools. Read resource renef://docs/lua-api for the full Lua API (Module/Memory/hook/Java/Syscall/Thread/File/OS/KCov). Renef is NOT Frida: no Interceptor/Java.perform. Java class names use slashes, e.g. 'com/example/Class'. Use pcall() around hooks for classes that may not exist.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| renef_statusA | Check the whole chain: adb device, adb port forward, renef_server reachability (ping/pong), and active target session. Start here. |
| renef_list_appsA | List installed packages on the device (via adb, no session needed). Set third_party_only=true to skip system packages. |
| renef_list_processesA | List running userland processes (pid + name) on the device, for renef_attach. |
| 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. |
| renef_server_startA | Start renef_server on the device as root (idempotent) and set up the adb port forward. Verifies with a ping. |
| renef_server_stopA | Stop renef_server on the device (kill as root). |
| renef_server_restartA | Restart renef_server on the device (stop, then start with port forward). |
| renef_server_logsA | Tail the renef_server log from the device (last lines, default 60). |
| renef_attachC | Attach to a running process and inject the renef agent. |
| 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. |
| renef_resumeA | Resume a spawn-gated process (after renef_spawn). |
| renef_disconnectA | Close the current target session (does not kill the target process). |
| 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. |
| renef_load_scriptC | Load a Lua script file from the MCP host machine and run it in the target. |
| 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). |
| renef_mem_readA | Read bytes from target memory and return a hexdump. addr accepts decimal or 0x-hex. size is capped at 4096 bytes. |
| renef_mem_read_valueB | Read an integer from target memory. size: 1, 2, 4 or 8 bytes (unsigned unless signed=true). |
| renef_mem_read_stringC | Read a NUL-terminated C string from target memory. |
| renef_mem_writeC | Write raw bytes to target memory. hex_bytes: hex string, spaces allowed, e.g. "1F 20 03 D5". |
| renef_mem_write_valueC | Write an integer to target memory. size: 1, 2, 4 or 8 bytes. |
| 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. |
| renef_module_listA | List loaded modules/libraries in the target process (base address, name, path). |
| renef_module_findB | Get the base address of a loaded module, e.g. renef_module_find("libc.so"). |
| renef_module_exportsB | List exported symbols of a module. Use filter to substring-match names, limit to cap output. |
| renef_module_symbolsB | List all symbols (including non-exported) of a module. filter/limit as in renef_module_exports. |
| renef_sectionsC | List ELF sections of a loaded library (upstream |
| renef_hook_generateB | Generate a ready-to-run Lua hook template (upstream |
| renef_framework_detectA | Detect the app framework (Flutter, React Native, Unity, Xamarin, Cordova/Ionic) by checking for its characteristic libraries. Needs a session. |
| 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. |
| 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. |
| 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. |
| renef_unhookA | Remove a hook by id (from renef_list_hooks), or "all" to remove every hook. |
| 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. |
| renef_backtraceA | Print the current thread call stack in the target process (useful inside hook debugging). |
| 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_get_scriptA | Return the Lua source of a bundled script (see renef_list_scripts), e.g. renef_get_script("flutter_ssl"). |
| renef_technique_listA | List available technique knowledge bases and their platforms (e.g. ssl_pinning: android_native, flutter, react_native, unity, xamarin, cordova_ionic). |
| renef_techniqueB | Return the assembled technique guide for a platform, e.g. renef_technique("ssl_pinning", "flutter") or platform="react_native"/"unity"/"xamarin". |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| renef_expert | Guidance prompt for writing Renef Lua instrumentation scripts. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| resource_status | Current renef chain status as compact text. |
| resource_lua_api | Full Renef Lua API reference (Module, Memory, hook, Java, Syscall, Thread, File, OS, KCov). |
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).