Skip to main content
Glama

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 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).

Related MCP server: renef-mcp

Tools (38)

Status and discovery (no target needed)

  • renef_status() — adb devices, port forward, server ping/pong, session state

  • renef_list_apps(third_party_only) — installed packages

  • renef_list_processes() — running processes, for renef_attach

Server lifecycle (no session needed)

  • renef_server_deploy(source) — push renef_server + libagent.so to the device, set permissions and the SELinux context the agent needs, verify by md5. With the default source="auto" it prefers a local Renef build and otherwise downloads the pinned, CI-built binaries (SHA-verified) — no NDK required

  • renef_server_start() / renef_server_stop() / renef_server_restart() — root-managed lifecycle with ping verification

  • renef_server_logs(lines) — tail the server log on the device

Session

  • renef_attach(pid) — inject the agent into a running process

  • renef_spawn(package) — spawn an app gated at startup (ptrace pause) and inject the agent. The first exec auto-resumes it, or call renef_resume without a script

  • renef_resume() — resume a spawn-gated process

  • renef_disconnect() — close the session; the target keeps running

Execution

  • renef_exec(lua) — run Lua in the target and get back its print() output. The workhorse, and multi-line Lua is fine

  • renef_load_script(path) — run a Lua file from the host machine

Memory

  • renef_mem_scan(pattern, module) — scan for a hex pattern. Prefer module="libfoo.so", which uses Lua Memory.search and 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 cap

  • renef_mem_read(addr, size) — hexdump, up to 4096 bytes

  • renef_mem_read_value(addr, size, signed) — integer read, 1/2/4/8 bytes

  • renef_mem_read_string(addr, max_len) — NUL-terminated C string

  • renef_mem_write(addr, hex_bytes) — write raw bytes

  • renef_mem_write_value(addr, value, size) — write an integer, verified by reading it back

  • renef_mem_patch(addr, hex_bytes) — like mem_write but via Memory.patch, which handles mprotect itself, so read-only code pages are fair game

Modules

  • renef_module_list() and renef_module_find(name) — loaded libraries, base addresses

  • renef_module_exports(name, filter, limit) / renef_module_symbols(name, filter, limit)

  • renef_sections(lib) — ELF sections of a loaded library

  • renef_framework_detect() — flags Flutter, React Native, Unity, Xamarin or Cordova by their characteristic libraries

  • renef_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; pass caller="libtarget.so" for the PLT/GOT backend. Callbacks are Lua statements over args[0..7] (onEnter) and retval (onLeave). Find offsets with renef_module_exports first

  • renef_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] is this, args[2..] are the parameters, and args.skip = true bypasses a void method

  • renef_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/spawn

  • renef_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 like flutter_ssl, ssl_unpin and root_bypass

  • renef_get_script(name) — the Lua source, ready for renef_load_script

Technique knowledge base (vendored from ahmeth4n/renef-mcp, MIT)

  • renef_technique_list() — categories and platforms; currently ssl_pinning for android_native, flutter, react_native, unity, xamarin and cordova_ionic

  • renef_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() downloads renef_server and libagent.so that CI builds from the pinned renef source (see renef_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.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:

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-mcp

Or 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 tools
renef_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

    B3.3/5.0

    Scored across 38 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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).

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      F
      maintenance
      An 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.
      10
      70
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Renef, providing dynamic instrumentation and reverse engineering capabilities for Android ARM64, including native hooking, Java interception, and memory manipulation.
      9
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables AI agents to inspect APKs and resources, analyze native libraries, trace runtime behavior with Frida, and connect app screen actions to code through ADB.
      89
      1
      MIT