Skip to main content

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

Source distribution for android-renef-mcp 0.1.1
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)

Table of built distributions (wheels) for android-renef-mcp 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page