# frida-mobile-mcp [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/monkeywave/frida-mobile-mcp  
**GitHub Stars:** 15  
**npm Downloads (last month):** 792  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/frida-mobile-mcp

## Description
Mobile Frida MCP Server - AI-powered mobile app exploration and testing via Frida instrumentation; runs next to REA, ReVa (Ghidra) and IDA MCP servers

## Tools
Capabilities this server exposes over MCP:

- **get_status** — Get an overview of connected devices, active sessions (with platform, script count and last activity), hooks, traces, and the most recent session detaches / process crashes (recent_detaches). Use this first to understand what is available before starting any instrumentation work, and after a session is lost to see why.
- **frida_help** — Get help on how to use frida-mobile-mcp tools. Use this to learn about available capabilities, method hooking patterns, address notation, script kinds (classic/esm/bundle), TLS capture and example workflows. Topics: overview, hooking, tracing, memory, scripts, native, tls, mobile, examples, advanced, evasion, script_catalog, script_api, recipes, interop.
- **explore_app** — Launch a mobile app and gather comprehensive initial context including loaded classes, modules, and libraries. This is the recommended starting point for any app analysis. The app will be spawned in suspended mode, instrumented, then resumed. Returns: pid, platform, loaded modules, and filtered class list.
- **get_app_info** — Identify the exact installed artifact of an app: version, SDK levels, debuggable flag, installer, data/native-lib dirs and every APK (base + splits) with on-device sha256 and size (Android via fixed adb queries: pm path, dumpsys package, sha256sum, stat). With pull_to, pulls the APKs to the host and verifies their sha256 against the device. Use it to hand the same APK that runs to a static tool (REA inspect_android_package, jadx) and to record in a report which artifact was analysed. iOS returns the Frida application parameters without hashes.
- **hook_method** — Hook a method to intercept calls with auto device/session management. Provide the app target (or a session_id of an existing session) and method pattern. Supports Java methods (Android: "com.example.Class.method"), Objective-C methods (iOS: "-[NSURLSession dataTaskWithRequest:]"), and native functions in any notation: "libssl.so!SSL_read" (module export), "libfoo.so+0x1234" or "libfoo.so+4660" (module-relative offset, as shown by Ghidra/IDA), "0x7f1234567890" (absolute address), or "!open" (global export searched across all modules). Native backtraces are reported as "module+0xoff (symbol)". Java overloads: append a signature to hook ONE overload, e.g. "com.pkg.Class.encrypt(byte[], java.lang.String)" (without one, every overload is hooked). Static-analysis findings can be passed as "evidence" instead of "method": {module, offset} (image-base-relative offset from Ghidra/IDA) or {module, address, image_base}, or {class, signature} for Java (jadx/describe_class/JVM descriptor). After hooking, use get_messages to retrieve intercepted calls.
- **trace_method** — Trace function calls matching a pattern for a specified duration. Simplified frida-trace equivalent. Supports glob patterns like "com.example.network.*" for Java, "-[NSURL*]" for ObjC, and "libssl.so!SSL_*" for native. Returns all captured invocations after the duration expires.
- **execute_script** — Execute a custom Frida JavaScript/TypeScript script in a target process (Frida 17 agent). Provide either inline source code or a file path. Three source kinds are supported and detected automatically (override with `source_kind`): classic (non-module) JavaScript, where the `Java` and `ObjC` globals are auto-injected by platform (Java on Android, ObjC on iOS/macOS; override with `bridges`) so legacy Java.perform()/ObjC scripts keep working with their own line numbers; ES modules (import/export, JS or TS) such as `import Java from "frida-java-bridge"`, which are compiled on the host with the Frida Compiler (bridges are bundled by the imports, so `bridges` is ignored); and frida-compile bundles (source starting with the 📦 marker), which are loaded as-is. The full Frida API (Interceptor, Memory, Module, Process, NativePointer, ...) is available everywhere. Results are sent via send() and retrieved with get_messages. `timeout_ms` bounds the script's initial run (default 30000 for one-shot scripts, 0 for persistent ones); a script that overruns is interrupted, then terminated, and the call fails with SCRIPT_TIMEOUT including the partial messages. Use validate_script to check syntax/types without a device. Note: custom scripts must be explicitly enabled in config (allowCustomScripts: true).
- **run_prebuilt_script** — Run a pre-built Frida script from the built-in library. Call without script_name to list all available scripts. Available scripts include: ssl_pinning_bypass, root_jailbreak_bypass, class_enumeration, method_hook, crypto_monitor, network_inspector, keychain_prefs, filesystem_monitor, anti_frida_evasion.
- **search_classes_and_methods** — Search for classes and their methods by pattern in a running app. Combines class enumeration and method listing. Use regex patterns like "Login", "com\.example\.auth.*", or "NSURLSession". Returns matching classes with their methods when include_methods is true.
- **describe_class** — Return the full shape of ONE loaded app class so you can pick an exact method overload before hooking. Android: every declared method with parameter types, return type, modifiers and a ready-to-use `signature` (e.g. "encrypt(byte[], java.lang.String)"), constructors (as "$init(...)"), fields, superclass and interfaces; searches all class loaders. iOS: selectors with Objective-C type encodings, superclass and protocols. Pass a returned signature verbatim to hook_method as evidence: {class, signature} to hook exactly that overload. The class must already be loaded; if it is not, use watch_loads or search_classes_and_methods.
- **discover_crypto** — Find where an app actually performs cryptography (or any API family), without assuming javax.crypto. In one pass it enumerates: Java/ObjC classes whose name matches a pattern (across all class loaders), and native export symbols matching the pattern or a known crypto/TLS symbol (EVP_*, SSL_read/write, CCCrypt, RC4, AES_, mbedtls_, ...). Returns ranked candidates — app-owned classes first, then framework classes, then native symbols. Native candidates hook as-is ("module!symbol"); Java/ObjC candidates are CLASSES — pass "Class.method" to hook_method (method names are in the `java` list), or trace "Class.*". Use this before guessing a hook when the goal is "capture the key", "trace the cipher", etc.
- **find_secrets_in_memory** — Scan live process memory for the STRUCTURE of secrets, not just names or byte patterns. Finds keys even when you never reached the code that uses them: an RC4 key schedule (256-byte permutation of 0..255, byte[] or Java int[256] — the rc4demo case), an AES key schedule (aeskeyfind-style verification, AES-128/192/256, both encryption AND decryption schedules — and it is MODE-INDEPENDENT: the same expanded key backs CBC/CTR/GCM/XTS), a ChaCha20/XChaCha20 key (located by the exact "expand 32-byte k" sigma constant, key at +16) and Salsa20 state, high-entropy 16/24/32-byte buffers (candidate symmetric keys), PEM/DER private-key headers, and JWT tokens. Raw-key-only ciphers (AES-NI with no in-memory schedule) fall back to high_entropy_key + monitor_crypto at the API boundary. Defaults to writable (heap) ranges where live keys sit. Returns candidates with a module+offset address and a hex/text preview; read the full bytes with read_memory, or hand one to generate_memory_pattern. Complements discover_crypto (name-only) and scan_memory (fixed byte-pattern only).
- **trace_coverage** — Arm a broad set of cheap entry-hooks over a target set and track which have been REACHED (covered) vs which are still COLD — the reachability signal for a drive loop. Unlike trace_method (time-boxed, logs every call), this is persistent and entry-only: it answers "what code have I NOT exercised yet, so where should I keep driving?". Scope can be a single class (all its methods), a class/package glob ("com.example.*"), a native module glob ("libfoo.so!*"), or an ObjC pattern ("-[MyClass *]"). Workflow: arm it, then alternate trigger_and_wait (drive the UI) with trace_coverage {report_only:true} to watch the cold set shrink. Each target fires at most once (first-seen), so hot methods do not flood output.
- **monitor_crypto** — Cast a wide net over cryptography instead of hooking one method at a time. In a single persistent script it discovers and hooks ALL likely crypto sinks at once — app-owned Java classes whose name matches a crypto pattern (every overload of every declared method), plus the framework sinks that almost every app funnels through: javax.crypto Cipher (doFinal/init/getInstance), Mac, MessageDigest and SecretKeySpec on Android; CommonCrypto (CCCrypt, CCCryptorCreate, CC_SHA256, CC_MD5) on iOS; and native OpenSSL/BoringSSL (EVP_*Update, RC4, AES_set_encrypt_key). Every call dumps its byte[]/String key, input and output as hex, so you capture the key and plaintext WITHOUT knowing the exact method. This is persistent instrumentation (like hook_method): it returns immediately, then you drive the app and read the captured events with get_messages. Use when the goal is "grab the key / see the plaintext" and discover_crypto gave too many candidates to hook by hand.
- **generate_memory_pattern** — Turn a secret you already located (e.g. from find_secrets_in_memory) into a reusable anchor pattern: a stable byte signature near the key plus the offset from it to the key. Reads a small window around the address, then derives a recognizer-aware anchor (ChaCha sigma constant, PEM/DER/JWT header, or the longest stable run adjacent to the key). Returns a scan_memory pattern to re-locate the secret by shape across restarts, plus a friTap offsets entry and an ms_agent anchor to hand to capture_tls. This finds no new secret — give it one you have.
- **drive_coverage** — Autonomously drive the UI of an already-instrumented session toward uncovered code and stop the moment a signal fires. This arms NOTHING — first arm monitor_crypto and/or trace_coverage, then call drive_coverage to tap through on-screen elements breadth-first, correlating each tap with new hook output (snapshot → tap → wait → delta, like trigger_and_wait in a loop). It stops on the first delta message that matches `stop_on` (default "crypto_event") or looks like a captured key/secret, when coverage stalls for several steps, when no untried elements remain, or at max_steps / the wall-clock cap. Supply `coverage_id` to measure the covered delta the drive produced. Use it to reach a crypto path hands-free instead of tapping manually; read the full output afterwards with get_messages.
- **watch_loads** — Install a persistent watcher that reports what the app does AFTER attach, straight into the session message buffer. Three signal families, each toggleable: (1) native libraries (.so) loaded late (dlopen/android_dlopen_ext), observed via Frida's loader module-load notifications — no dlopen hook, so it will not destabilize the target — meaning a library that only appears after a UI action is still seen; (2) Java classes loaded late via ClassLoader.loadClass (Android only; the Java.available guard makes it a no-op elsewhere); (3) anti-instrumentation / anti-debug reads of canonical /proc locations (maps, status, task) via open/fopen. The watcher stays loaded and keeps emitting: drive the app (e.g. mobile_action), then call get_messages to read the watch_event entries. Pair with discover_crypto / hook_method once a late-loaded target shows up. Set spoof=true (needs memoryWriteEnabled) to go beyond reporting and actively scrub Frida signatures / zero TracerPid from those /proc reads; for a fuller stealth set use the anti_frida_evasion prebuilt script.
- **read_memory** — Read raw memory from a target process. Requires an active session. Address in any notation: "0x7fff12345678" (absolute), "libfoo.so+0x1234" or "libfoo.so+4660" (module-relative offset), "libssl.so!SSL_read" (module export), or "!open" / "open" (global export). Max 4MB per read. Returns hex-encoded bytes plus the resolved absolute address and module+offset (rva).
- **write_memory** — Write raw bytes to process memory. DISABLED by default for safety - enable via config (memoryWriteEnabled: true). Provide hex-encoded data. Address in any notation: "0x7fff12345678" (absolute), "libfoo.so+0x1234" or "libfoo.so+4660" (module-relative offset), "libssl.so!SSL_read" (module export), or "!open" / "open" (global export).
- **scan_memory** — Scan process memory for a byte pattern. Pattern format: "48 89 5c 24 ?? 57" where ?? is a wildcard. Optionally limit scan to a specific module.
- **bypass_ssl_pinning** — One-click SSL certificate pinning bypass for the target app. Auto-detects platform (Android/iOS) and applies the appropriate bypass techniques. On Android: hooks TrustManager, OkHttp CertificatePinner, and Conscrypt. On iOS: hooks SecTrust, ATS, and BoringSSL verification. Returns which bypass methods were successfully installed.
- **capture_tls** — Capture TLS session keys (NSS key log format) and decrypted plaintext from the target using the friTap agent (OpenSSL/BoringSSL, Conscrypt, NSS, GnuTLS, wolfSSL, mbedTLS, Secure Transport, ...). By default the app is spawned suspended, friTap is loaded, then the app is resumed so early handshakes are caught. Key log lines are written to keylog_path (usable with Wireshark tls.keylog_file) and plaintext records are buffered as fritap_datalog messages for get_messages (requires full_capture). Needs the friTap agent bundle: pip install friTap, FRITAP_AGENT_PATH, or allow_download.
- **get_messages** — Retrieve buffered messages from active scripts and hooks. Messages include hook invocations, trace hits, script output (send() calls), and errors. Use "since" for pagination to get only new messages.
- **stop_instrumentation** — Clean up all hooks, scripts, and traces on a target. The "undo everything" tool. Detaches the Frida session and frees all resources. Use when you are done analyzing an app or want to start fresh.
- **unload_script** — Unload a single script (hook, trace or custom script) from a session while keeping the session attached. Use the script_id returned by hook_method, trace_method, execute_script or run_prebuilt_script. Hooks and traces that belong to the script are removed from the server state. Use stop_instrumentation to tear down a whole session instead.
- **mobile_action** — Gateway to mobile-mcp UI automation tools. Perform screenshots, taps, swipes, text input, app management and more. Common actions: mobile_take_screenshot, mobile_list_elements_on_screen, mobile_click_on_screen_at_coordinates (params: {x, y}), mobile_swipe_on_screen (params: {direction}), mobile_type_keys (params: {text}), mobile_launch_app (params: {appId}), mobile_list_apps. Call without action to see all available actions.
- **trigger_and_wait** — Correlate a UI action with instrumentation output in one round-trip: optionally perform a mobile_action (tap/launch/type) on the session's device, then block until at least `expect_messages` new messages/hook hits arrive (or timeout). Returns exactly the messages the trigger produced and which hooks fired. This is how you confirm "this tap ran the hooked code" — or learn "nothing fired, the hypothesis is wrong" — instead of tapping blindly and polling get_messages. Install hooks first (hook_method / discover_crypto → hook_method), then trigger_and_wait.
- **detect_app_technologies** — Detect what libraries, frameworks, and security mechanisms an app uses. Returns structured results with recommended script targets. Run this before choosing which pre-built scripts to use.
- **validate_script** — Check a Frida script for syntax, type and Frida 17 API problems without a device. Use it before execute_script. Classic (non-module) scripts get a JavaScript syntax check plus a lint for APIs removed in Frida 17 (static Module/Memory helpers, *Sync enumerators); referencing them throws at runtime, so they make the result not ok. ES module scripts (import/export) are compiled with the Frida Compiler: strict (default) runs a full TypeScript type check; plain JavaScript is only syntax-checked unless language is "ts". frida-compile bundles (source starting with the 📦 marker) are accepted as-is. Provide either inline source or a file path.
- **search_recipes** — Search the purpose-indexed library of ready-to-run classic-JS Frida recipes (custom Java crypto-key capture, standard javax.crypto key/IV, native export hook, JNI RegisterNatives discovery, custom-classloader enumeration, intent/deeplink trace, WebView bridge, iOS Keychain). Returns ranked recipes with their classic-JS source and usage notes; adapt the source and run it with execute_script. An empty query lists the whole library.
- **save_script** — Save a Frida script to the local library (~/.config/frida-mobile-mcp/scripts/) so it can be re-run later with run_saved_script or shared with export_script. Stores the raw source as <name>.js plus a <name>.json metadata file (sha256, size, created timestamp, description). Names are restricted to letters, digits, underscores and hyphens. Refuses to overwrite an existing script unless overwrite is true. Requires allowCustomScripts to be enabled in config.
- **list_saved_scripts** — List the Frida scripts saved in the local library (~/.config/frida-mobile-mcp/scripts/) with their description, creation time and size. Returns an empty list when nothing has been saved yet. No device is required.
- **run_saved_script** — Load a script previously saved with save_script into a target process. Resolves (or reuses) a session the same way execute_script does and runs the stored source as a custom agent: classic JavaScript gets the Java/ObjC bridges injected by platform, ES modules are compiled with the Frida Compiler, and frida-compile bundles are loaded as-is. Provide a target (app id, process name or PID) or an existing session_id. Requires allowCustomScripts to be enabled in config.
- **export_script** — Turn a Frida script into a STANDALONE classic .js file that the plain frida / frida-tools 17 CLI can run with `frida -U -f <package> -l file.js`, without this MCP server. The output is a header comment + the frida-mobile-mcp preamble helpers + the script body. Provide exactly one of source (inline) or name (a saved script). It does NOT bundle the Java/ObjC bridges (the Frida 17 CLI injects those) and does NOT emit TypeScript. With out_path the file is written and its path returned; otherwise the text is returned inline. This tool only transforms text, so it does not require allowCustomScripts.
- **get_evidence** — Return the persisted record of an earlier tool call by its evidence_id (from the result envelope or `_meta.evidence_id`): tool, redacted parameters, status, session, device, duration, script SHA-256 and the full structured result or error body. Records survive server restarts until evicted by the evidence size limits.
- **export_evidence_bundle** — Export persisted tool results as one JSON or Markdown report for a write-up or for a static-analysis tool. Select records by explicit evidence_ids, or by session_id and/or since (newest `limit` matches, exported oldest first). With out_path (absolute, under the current directory, the OS temp directory, ~/.config/frida-mobile-mcp/dumps or the evidence directory) the bundle is written to that file (mode 0600); otherwise it is returned inline.
- **list_devices** — Enumerate all Frida-visible devices including local, USB, and remote devices. Equivalent to frida-ls-devices CLI command.
- **select_device** — Explicitly select the active Frida device for subsequent operations.
- **get_device_info** — Get detailed information about a device including OS version, architecture, and system parameters.
- **list_processes** — List running processes on the target device. Equivalent to frida-ps CLI command.
- **list_applications** — List installed and running applications on the target device.
- **get_frontmost_application** — Get the currently foreground application on the device.
- **spawn_process** — Spawn a new process in suspended state for early instrumentation. The process will be paused until resume_process is called.
- **attach_process** — Attach to an already running process by PID or name.
- **resume_process** — Resume a suspended process (after spawn_process).
- **kill_process** — Kill a process on the target device.
- **detach_session** — Detach from a specific Frida session, unloading all scripts.
- **spawn_gating** — Enable, disable, or list device-wide spawn gating. When enabled, every newly spawned process (including app-launched child/isolated processes that often run RASP/anti-Frida checks) is held suspended until released. Use "list" to see pending spawns and children, then attach_process + hook_method, and resume_process to release each by PID.
- **child_gating** — Enable or disable child gating on an existing session. When enabled, processes forked/exec'd by the instrumented process are held so they can be instrumented too (e.g. an app that moves detection into a child process). Requires device-wide spawn gating to catch the held children; list them with spawn_gating action="list".
- **eternalize_script** — Make a loaded script survive session detach: frida pins it in the target so it keeps running after we detach (or the host exits). Trade-off — once eternalized the script can no longer send messages back, be unloaded, or be inspected; it is fire-and-forget persistence. Use it to leave a bypass/monitor running while you free the session. Give the session_id and the script_id returned by hook_method / execute_script / watch_loads.
- **list_sessions** — List all active Frida sessions managed by this server.
- **enumerate_modules** — List loaded modules (shared libraries) in the target process with name, base, end (base+size), size and path. Optional case-insensitive regex `filter` matches against name or path. Use base/end to rebase a Ghidra/IDA project; Addresses are absolute runtime pointers; subtract the module base to get the Ghidra/IDA offset (or use resolve_address with a "module+0xoff" target).
- **enumerate_exports** — List exports (functions and variables) of a specific module, paginated with offset/limit. Hook results with hook_method using "module!name". Addresses are absolute runtime pointers; subtract the module base to get the Ghidra/IDA offset (or use resolve_address with a "module+0xoff" target).
- **enumerate_imports** — List imports of a specific module (functions it calls in other libraries), paginated with offset/limit. Each entry carries the providing `module` when known, so "module!name" can be hooked directly. Addresses are absolute runtime pointers; subtract the module base to get the Ghidra/IDA offset (or use resolve_address with a "module+0xoff" target).
- **enumerate_symbols** — List symbols (including non-exported/debug symbols) of a specific module. Only available on Linux, Android, iOS and macOS. Filtering (case-insensitive regex on the symbol name) and offset/limit paging happen inside the agent, so large symbol tables stay cheap. Addresses are absolute runtime pointers; subtract the module base to get the Ghidra/IDA offset (or use resolve_address with a "module+0xoff" target).
- **hook_function** — Low-level hook with custom onEnter/onLeave JavaScript handlers. For advanced use when hook_method does not provide enough control. Custom handler bodies require allowCustomScripts: true in config; without them the hook sends default enter/leave events. Handler bodies are compiled as functions (new Function) inside the agent: `this` is the Interceptor invocation context (this.context, this.returnAddress, this.threadId, and any fields you set in on_enter are visible in on_leave). Java/ObjC globals are available (auto-injected by platform). A static-analysis finding can be passed as evidence {module, offset} or {module, address, image_base} instead of target.
- **unhook_function** — Remove a specific hook by its hook ID.
- **resolve_address** — Translate between absolute process addresses and static-analysis coordinates. Give "0x7f..." to get module+0xoffset (+ nearest symbol); give "libfoo.so+0x1234" or "libfoo.so!func" to get the absolute runtime address. Use it to hand addresses between Frida and Ghidra/IDA.
- **analyze_native_function** — Static-style analysis of a native function at runtime: function range (Process.findFunctionRange), basic blocks and edges (Frida 17.12+ ControlFlowGraph; falls back to linear disassembly until the first return and says so in `limitations`), and the first instructions. All addresses are reported as absolute and as module+0xoffset for cross-referencing with Ghidra/IDA.
- **dump_module_memory** — Dump a loaded module from process memory to a file on the host (e.g. an unpacked/decrypted library). The file is laid out base-relative: file offset 0 is the module base, readable ranges are copied in 1 MiB chunks, unreadable gaps are zero-filled, so it can be imported into Ghidra/IDA as a raw binary at the returned `base`. out_path must be absolute and inside the current directory, the OS temp directory or ~/.config/frida-mobile-mcp/dumps.
- **list_threads** — List the threads of the target process (id, name, state, current pc as module+0xoffset). With backtraces: true each thread also gets a symbolised backtrace (up to 8 frames) captured from its register context.
- **frida_server_status** — Report whether frida-server is running on an Android device (via adb): its PIDs, the device CPU ABI, the matching frida release arch, and the exact GitHub .xz asset URL to download for the installed frida-node version.
- **frida_server_install** — Push a local frida-server binary to an Android device and make it executable (adb push + chmod 755). Download and decompress the correct .xz for the device ABI first (frida_server_status gives the asset URL).
- **frida_server_start** — Start frida-server detached on an Android device (adb shell, daemonized with -D), optionally via su. Supports a custom listen address/port and a renamed binary path for stealth setups, then confirms the server came up.
- **frida_server_stop** — Stop frida-server on an Android device by sending a signal to the matching process (adb shell pkill, optionally via su), then report any remaining PIDs.
- **adb_shell** — Run an arbitrary shell command on an Android device via `adb shell`. DISABLED by default: arbitrary command execution must be enabled with allowAdbShell (config) or FRIDA_MCP_ALLOW_ADB_SHELL=1. Enforces allowedDevices.
- **adb_logcat** — Dump the last N lines of the Android logcat (one-shot, `adb logcat -t N`), optionally filtered by tag:priority specs, or clear the buffer. Useful for correlating app log output with instrumentation events.
- **adb_pull** — Pull a file from an Android device to the host (`adb pull`). Enforces allowedDevices.
- **adb_push** — Push a file from the host to an Android device (`adb push`). Enforces allowedDevices.
- **adb_forward** — Manage adb port forwards (`adb forward`): add a local->remote forward, remove one, or list them. Use it to reach a frida-server on a non-default device port (e.g. local "tcp:27042" -> remote "tcp:12345").
- **inject_library** — Inject a native agent library (.so/.dylib) from the host into a target process via Frida's injector, independent of the JS engine — the parity path for a prebuilt Frida gadget/agent or a custom .so. Runs arbitrary native code in the target, so it needs allowNativeInjection (a capability separate from allowCustomScripts). The library must match the device architecture (arm64-v8a etc.); its optional exported entrypoint is called with the data string. Returns the frida injectee id.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "frida-mobile-mcp": {
    "command": "npx",
    "args": ["-y","frida-mobile-mcp"]
  }
}
```

## Documentation & README

# frida-mobile-mcp

[![npm](https://img.shields.io/npm/v/frida-mobile-mcp.svg)](https://www.npmjs.com/package/frida-mobile-mcp)
[![skills.sh](https://skills.sh/b/monkeywave/frida-mobile-mcp)](https://skills.sh/monkeywave/frida-mobile-mcp/mobile-dynamic-analysis)
[![CI](https://github.com/monkeywave/frida-mobile-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/monkeywave/frida-mobile-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node >=22.12](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen.svg)](package.json)

An MCP server that gives AI agents dynamic instrumentation of Android and iOS apps through Frida 17, and runs next to REA, ReVa (Ghidra) and IDA MCP servers. It exposes 71 tools: high-level ones that manage devices, sessions and scripts for you (explore an app, hook a Java/ObjC/native method, trace calls, map reachability coverage and autonomously drive the UI toward it, find secrets in memory and turn them into reusable friTap patterns, cast a wide net over crypto, bypass SSL pinning, capture TLS keys and plaintext with friTap, run prebuilt analysis scripts, validate custom scripts) and low-level primitives (spawn/attach, module and symbol enumeration, address resolution, control-flow analysis, memory dumps). Addresses use the same `module+0xoffset` notation as Ghidra/IDA so results move between static and dynamic tools without conversion, and every result carries an evidence envelope (`evidence_id`, `limitations`, `coverage`). Optional UI automation goes through [mobile-mcp](https://github.com/mobile-next/mobile-mcp).

## Quick start

```bash
npx frida-mobile-mcp                      # stdio MCP server (default `serve` command)
frida-mobile-mcp doctor                   # check Node, frida-node, adb, devices, frida-server, bridge bundles
frida-mobile-mcp setup --client cursor    # write the server into a client config (claude-code, claude-desktop, cursor, vscode, windsurf, codex)
frida-mobile-mcp gadget --platform android --print   # generate a frida-gadget config.json + APK/IPA repackaging guidance
```

The `gadget` command generates a [frida-gadget](https://frida.re/docs/gadget/) `config.json` (`--interaction listen` or `--interaction script`) and prints the APK/IPA repackaging steps. Embedding the gadget is the only way to instrument native detection that runs in `.init_array` / `JNI_OnLoad` **before** an attach-time script can load, and it removes the frida-server `:27042` port as a fingerprint — see `frida_help({ topic: "evasion" })`.

Claude Code:

```bash
claude mcp add frida -- npx -y frida-mobile-mcp
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "frida": {
      "command": "npx",
      "args": ["-y", "frida-mobile-mcp"],
      "env": { "FRIDA_DEVICE_ID": "emulator-5554" }
    }
  }
}
```

Per-client instructions, HTTP mode and remote frida-server setup are in [docs/clients.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/docs/clients.md). A Claude Desktop extension manifest (`manifest.json`, MCPB) and an MCP registry entry (`server.json`) ship in the repo.

## Requirements

- Node.js >= 22.12 (CI runs 22 and 24 on Linux, macOS and Windows). `npm install` runs the `frida` package's install script, which downloads the native frida-node prebuild.
- A device or emulator running **frida-server 17.x**. This package depends on frida-node `^17.24.3`; frida-server on the device must have the same major version (17) and ideally the same minor version. `frida-mobile-mcp doctor` prints both versions and flags mismatches.
- Android: download the matching `frida-server-17.x.y-android-<arch>.xz` from <https://github.com/frida/frida/releases>, then

  ```bash
  xz -d frida-server-17.24.3-android-arm64.xz
  adb push frida-server-17.24.3-android-arm64 /data/local/tmp/frida-server
  adb shell "chmod 755 /data/local/tmp/frida-server"
  adb shell "su -c '/data/local/tmp/frida-server &'"
  ```

- iOS: a jailbroken device with the matching Frida package from the Frida Cydia/Sileo repository. Non-jailbroken devices need the app repackaged with the Frida Gadget; the server then attaches to the gadget-enabled process like any other.
- Optional: `pip install friTap` for `capture_tls` (otherwise the pinned agent is downloaded on first use), and network access for `npx -y @mobilenext/mobile-mcp@latest` on first `mobile_action`.

## What is new for Frida 17

- **Bridges are bundled.** Frida 17 no longer ships the Java/ObjC bridges in the GumJS runtime. `npm run build:bridges` bundles `frida-java-bridge` and `frida-objc-bridge` into `dist/bridges/{java,objc}.js`; the server injects the right one by platform (Java on Android, ObjC on iOS/macOS) ahead of every script.
- **Legacy scripts still work.** `execute_script` runs classic (non-module) scripts through `Script.evaluate`, so a `Java.perform(...)` script written for Frida 16 runs unchanged and keeps its own line numbers in errors. ES modules (`import Java from "frida-java-bridge"`, JS or TS) are compiled on the host with the Frida Compiler; frida-compile bundles (starting with the `📦` marker) are loaded as-is.
- **Removed APIs are linted.** `validate_script` flags the static `Module.findExportByName`/`findBaseAddress`/`enumerateExports`, `Memory.readX`/`writeX` and `*Sync` enumerators that throw on Frida 17 and suggests the Module-instance / `NativePointer` replacements. Generated scripts get `findExport(lib, name)` and `hookNative(lib, name, callbacks)` helpers from the agent preamble, and template options as `__FRIDA_MCP__.options`.
- `analyze_native_function` uses `Process.findFunctionRange` and the Frida 17.12+ `ControlFlowGraph` (with a linear-disassembly fallback reported in `limitations`).

## Tool reference

### Tier 1: high-level tools

| Tool | Description |
|------|-------------|
| `get_status` | Connected devices, active sessions (platform, script count, last activity), hooks, traces and recent detaches/crashes. Run first and after a session is lost. |
| `frida_help` | Topic help: overview, hooking, tracing, memory, scripts, native, tls, mobile, examples, advanced, evasion, script_catalog, script_api, recipes, interop. |
| `detect_app_technologies` | Fingerprint libraries, frameworks and security mechanisms; returns recommended script targets. |
| `explore_app` | Spawn an app suspended, instrument, resume; returns pid, platform, modules and a filtered class list. |
| `get_app_info` | Identify the installed artifact: version, SDK levels, debuggable, installer and every APK (base + splits) with on-device sha256/size; `pull_to` pulls and hash-verifies them for a static tool such as REA `inspect_android_package`. iOS: Frida app parameters only. |
| `search_classes_and_methods` | Regex search over classes (and methods with `include_methods`) in a running app. |
| `describe_class` | Full shape of one loaded class: every method overload with parameter/return types and a hook-ready `signature`, constructors, fields, superclass/interfaces (ObjC: selectors with type encodings). Feed a signature to `hook_method` `evidence: {class, signature}`. |
| `discover_crypto` | Find where an app does crypto (or any API family) without assuming `javax.crypto`: ranked candidate hook targets across Java/ObjC classes and native symbols. |
| `find_secrets_in_memory` | Content-aware memory scan for the *structure* of secrets: RC4 S-box (`byte[]` or Java `int[256]`), AES key schedule (aeskeyfind — encryption **and** decryption, mode-independent), ChaCha20/Salsa20 keys (sigma constant), high-entropy 16/24/32-byte keys, PEM/DER private keys, JWTs. Finds keys without reaching the code that uses them. |
| `generate_memory_pattern` | Turn a located secret into a reusable **anchor pattern** (stable byte signature near the key + offset): re-locate it with `scan_memory`, or hand it to friTap via `capture_tls` (`patterns`/`offsets`). |
| `monitor_crypto` | Crypto-oracle wide net: discover and hook **all** likely crypto sinks at once (app-owned classes + `javax.crypto`/`Mac`/`MessageDigest`, iOS CommonCrypto, native OpenSSL/BoringSSL) and dump every key, input and output as hex. |
| `trace_coverage` | Reachability map: arm cheap persistent entry-hooks over a class/package/module scope and track **covered vs cold** targets across `trigger_and_wait` drives, so you know what code you have not yet exercised. |
| `drive_coverage` | Autonomously drive an instrumented session's UI toward uncovered code — taps on-screen elements breadth-first and stops the instant a crypto/secret signal fires (or coverage stalls / `max_steps`). Pair with `monitor_crypto` / `trace_coverage`. |
| `watch_loads` | Watch for late-loaded `.so` libraries and Java classes, plus anti-Frida probes; emits `watch_event` messages as the app runs. |
| `trigger_and_wait` | Perform a UI action and block until the resulting hook/message output arrives, so you learn which hook a tap fired (or that none did). |
| `hook_method` | Hook Java (`com.example.Class.method`), ObjC (`-[Class sel:]`) or native targets (`libssl.so!SSL_read`, `libfoo.so+0x1234`, `0x7f...`, `!open`) with auto session management; backtraces as `module+0xoff (symbol)`. |
| `trace_method` | frida-trace style tracing of glob patterns (`com.example.net.*`, `-[NSURL*]`, `libssl.so!SSL_*`) for a duration. |
| `execute_script` | Run a custom script: classic JS (bridges injected), ES module JS/TS (compiled with the Frida Compiler) or a frida-compile bundle. `timeout_ms` bounds the initial run. Requires `allowCustomScripts`. |
| `validate_script` | Syntax, type and Frida 17 removed-API check without a device. Use before `execute_script`. |
| `run_prebuilt_script` | Run one of the 9 prebuilt scripts below; call without `script_name` to list them. |
| `bypass_ssl_pinning` | One-click pinning bypass (Android: TrustManager, OkHttp CertificatePinner, Conscrypt; iOS: SecTrust, ATS, BoringSSL). |
| `capture_tls` | friTap: TLS session keys (NSS key log) and optional decrypted plaintext / synthetic pcap for OpenSSL/BoringSSL, Conscrypt, NSS, GnuTLS, wolfSSL, mbedTLS, Secure Transport and more. Accepts friTap `patterns`/`offsets` (e.g. from `generate_memory_pattern` or BoringSecretHunter) for stripped libraries. |
| `read_memory` | Read up to 4 MB at any address notation; returns hex plus absolute address and `module+offset`. |
| `write_memory` | Write hex bytes to memory. Disabled unless `memoryWriteEnabled`. |
| `scan_memory` | Byte-pattern scan (`48 89 5c 24 ?? 57`), optionally limited to a module. |
| `get_messages` | Buffered hook invocations, trace hits, `send()` output and errors; `since` paginates. |
| `get_evidence` | Re-read a persisted tool result (params, status, structured result) by `evidence_id`. |
| `export_evidence_bundle` | Export persisted results as a JSON or Markdown bundle, inline or to a file. |
| `stop_instrumentation` | Remove all hooks, scripts and traces on a target and detach. |
| `unload_script` | Unload a single script (hook, trace or custom) from a session while keeping it attached. |
| `mobile_action` | Gateway to mobile-mcp UI automation (screenshot, elements, tap, swipe, type, launch app, list apps). |
| `search_recipes` | Search the purpose-indexed library of ready-to-run classic-JS recipes (custom crypto-key capture, native/JNI hooks, classloader/intent/WebView, iOS Keychain); returns ranked recipes with source to adapt and run via `execute_script`. |
| `save_script` | Save a script under `~/.config/frida-mobile-mcp/scripts` for reuse. Requires `allowCustomScripts`. |
| `list_saved_scripts` | List scripts saved with `save_script`. |
| `run_saved_script` | Run a saved script by name against a target. Requires `allowCustomScripts`. |
| `export_script` | Export a script as a standalone classic `.js` that runs under the plain `frida -U -f <pkg> -l file.js` CLI (preamble + source; bridges provided by the frida-tools CLI, not bundled). |

### Tier 2: advanced primitives

| Tool | Description |
|------|-------------|
| `list_devices` | Local, USB and remote Frida devices (frida-ls-devices). |
| `select_device` | Select the active device by ID, type or remote host. |
| `get_device_info` | OS version, architecture and system parameters. |
| `list_processes` | Running processes (frida-ps). |
| `list_applications` | Installed and running applications. |
| `get_frontmost_application` | Foreground application. |
| `spawn_process` | Spawn suspended for early instrumentation; resume with `resume_process`. |
| `attach_process` | Attach to a running process by PID or name. |
| `resume_process` | Resume a suspended process. |
| `kill_process` | Kill a process. |
| `detach_session` | Detach a session and unload its scripts. |
| `list_sessions` | Sessions managed by this server. |
| `spawn_gating` | Enable / disable / list device-wide spawn gating — hold newly spawned (incl. child/isolated) processes suspended for early instrumentation; release with `resume_process`. |
| `child_gating` | Enable / disable child gating on a session so forked/exec'd child processes are held for instrumentation. |
| `eternalize_script` | Pin a loaded script in the target so it survives detach (fire-and-forget: no more messages/unload) — leave a bypass/monitor running while you free the session. |
| `enumerate_modules` | Loaded modules with name, base, end, size, path; regex `filter`. |
| `enumerate_exports` | Exports of a module, paginated. |
| `enumerate_imports` | Imports of a module with the providing module, paginated. |
| `enumerate_symbols` | Symbols including non-exported/debug symbols; regex filter and paging inside the agent (Linux, Android, iOS, macOS). |
| `resolve_address` | Translate `0x7f...` to `module+0xoffset` (+ nearest symbol) and `module+0xoff` / `module!sym` to an absolute address. |
| `analyze_native_function` | Function range, basic blocks and edges, first instructions; addresses as absolute and `module+0xoffset`. |
| `dump_module_memory` | Dump a module base-relative to a host file (under cwd, the temp dir or `~/.config/frida-mobile-mcp/dumps`) for raw import into Ghidra/IDA. |
| `list_threads` | Threads with id, name, state, current pc as `module+0xoffset`; optional 8-frame backtraces. |
| `hook_function` | Low-level `Interceptor` hook on a `session_id` with optional custom `on_enter`/`on_leave` bodies (custom bodies need `allowCustomScripts`). |
| `unhook_function` | Remove a hook by ID. |
| `frida_server_status` | Android (adb): report frida-server PIDs, device CPU ABI, matching frida release arch, and the GitHub `.xz` asset URL for the installed frida-node version. |
| `frida_server_install` | Android (adb): push a local (decompressed) frida-server binary to the device and `chmod 755` it. |
| `frida_server_start` | Android (adb): start frida-server daemonized (optionally via `su`) with a custom listen address/port and binary name — a non-default port/name evades `:27042`/`frida-server` scans. Enforces `allowedDevices`. |
| `frida_server_stop` | Android (adb): signal the matching frida-server process to stop (`pkill`, optionally via `su`). |
| `adb_shell` | Android (adb): run an arbitrary device shell command. **Disabled by default** — requires `allowAdbShell` (config) or `FRIDA_MCP_ALLOW_ADB_SHELL=1`. |
| `adb_logcat` | Android (adb): dump the last N logcat lines (one-shot), optional `tag:priority` filters, or clear the buffer. |
| `adb_pull` / `adb_push` | Android (adb): move files between host and device. |
| `adb_forward` | Android (adb): add / remove / list port forwards (reach a frida-server on a non-default device port). |
| `inject_library` | Inject a native library (.so/.dylib) from the host into a process via Frida's injector, independent of the JS engine — the parity path for a prebuilt gadget/agent or custom .so. **Disabled by default** — needs `allowNativeInjection` (config) or `FRIDA_MCP_ALLOW_NATIVE_INJECTION=1` (a capability separate from `allowCustomScripts`) and an architecture-matched library. |

### mobile_action gateway

`mobile_action({ action, params })` forwards to a lazily spawned mobile-mcp process (`npx -y @mobilenext/mobile-mcp@latest` by default, configurable via `mobileMcp`, disabled with `--no-mobile-mcp`). Call it without `action` to list the available actions. All Frida tools work without it; when it cannot start the error is `MOBILE_MCP_UNAVAILABLE`.

The server also exposes `frida://` resources (version, devices, processes, apps, sessions, messages, script catalog, persisted evidence via `frida://evidence` and `frida://evidence/{id}`) and five workflow prompts (`explore_app`, `security_audit`, `trace_functionality`, `write_frida_script`, `hunt_secrets`).

## Prebuilt scripts

| Script | Purpose |
|--------|---------|
| `ssl_pinning_bypass` | Bypass certificate pinning (TrustManager, OkHttp, Conscrypt, WebView; SecTrust, ATS, BoringSSL, AFNetworking) |
| `root_jailbreak_bypass` | Bypass root/jailbreak detection (Java, SystemProperties, native fopen/access/stat, canOpenURL, sysctl) |
| `class_enumeration` | List loaded Java/ObjC classes with a regex filter, optionally with methods |
| `method_hook` | Generic method hook (Java/ObjC methods or a native `target`) with argument and return value logging |
| `crypto_monitor` | javax.crypto, CommonCrypto and OpenSSL calls |
| `network_inspector` | Sockets, DNS, UDP and TLS SSL_read/SSL_write (plaintext bytes with `log_data`) |
| `keychain_prefs` | iOS Keychain and Android SharedPreferences access |
| `filesystem_monitor` | File I/O and SQLite |
| `anti_frida_evasion` | Observe (`mode=report`, default) or neutralize (`mode=spoof`, needs `memoryWriteEnabled`) the native primitives RASP uses to detect Frida: `/proc/self/{maps,status,task}` reads, `strstr` "frida" greps, thread-name / `dlopen` probes, and iOS dyld image scans |

## Address notation and evidence envelope

Every tool that takes or returns a native address uses one vocabulary:

| Form | Meaning | Example |
|------|---------|---------|
| `module!symbol` | export or ELF/Mach-O symbol | `libssl.so!SSL_write` |
| `module+0xOFFSET` | offset from the module base (Ghidra/IDA RVA); decimal `libfoo.so+4660` also accepted | `libfoo.so+0x1a2b0` |
| `0xADDRESS` | absolute runtime address | `0x7f3a1c2b1234` |
| `symbol` / `!symbol` | global export searched across all modules | `!open` |

Results prefer `module+0xoffset` so a static tool can decompile at image base + offset; absolute addresses appear only outside known modules and come with a `limitations` entry.

Every successful call returns `result`, `evidence_id` (UUID, also written to the audit log), `limitations[]`, `coverage` (`complete` | `unknown`), `session_context` and `suggested_next`. Errors carry `code`, `category`, `retryable`, `remediation` and `recovery_actions`. Every result, errors included, is also persisted to the evidence store and retrievable by its `evidence_id` via `get_evidence`, `export_evidence_bundle` and the `frida://evidence/{id}` resource (`frida://evidence` lists the latest 100). Field semantics and the error-code table are in [docs/interop.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/docs/interop.md); the agent workflow around them is in [skills/mobile-dynamic-analysis/SKILL.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/skills/mobile-dynamic-analysis/SKILL.md).

## Working with REA, ReVa and IDA

frida-mobile-mcp is built to run next to ReVa (Ghidra), ida-pro-mcp (IDA Pro) and REA: the static side answers what the code says, this server answers what it does at runtime. A static tool finds `libfoo.so+0x1234`; `hook_method` or `analyze_native_function` take that string as-is; backtraces and `resolve_address` give offsets back in the same form for decompilation. `enumerate_modules` returns `base`/`end` for rebasing a Ghidra/IDA project, `dump_module_memory` writes a base-relative image of an unpacked library for raw import, and `capture_tls` shows the bytes a statically found wrapper actually puts on the wire. A three-server client configuration and a full static -> dynamic -> static walkthrough are in [docs/interop.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/docs/interop.md).

[REA](https://github.com/morluto/rea) covers static Android analysis (`inspect_android_package`, `inspect_android_method`), ADB housekeeping and a generic Frida lane for desktop binaries; this server covers the mobile runtime (Java/ObjC bridges, prebuilt scripts, TLS keys, memory, UI driving). Register both in the same client, start with `get_app_info` so both servers analyse the same APK hash, and keep the combined catalog small with `FRIDA_MCP_TOOL_PROFILE=core` and `FRIDA_MCP_TOOLS_EXCLUDE=adb_*,frida_server_*`. Both servers return an evidence envelope with citable `evidence_id`s and an `export_evidence_bundle` tool, so one finding ledger can cite both. Routing rules, install lines, the field and error-code mapping and an APK -> static -> hook -> report walkthrough are in [docs/rea.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/docs/rea.md).

## HTTP transport

```bash
frida-mobile-mcp --transport http --port 3000                 # loopback (127.0.0.1), token optional
FRIDA_MCP_HTTP_TOKEN=<token> frida-mobile-mcp --transport http --host 0.0.0.0 --port 3000
```

Streamable HTTP endpoint at `/mcp` with one MCP session per client (`Mcp-Session-Id`); `DELETE /mcp` with that header ends the session. The server binds to loopback by default; a Bearer token (`--http-token` or `FRIDA_MCP_HTTP_TOKEN`) is mandatory when `--host` is not a loopback address and the server refuses to start without one. `Host` and `Origin` headers are validated against the bound host (DNS-rebinding protection). There is no TLS; use a reverse proxy or SSH tunnel across networks. `--port 0` picks a free port; the bound URL is printed as a JSON line on stderr. Full curl examples: [docs/clients.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/docs/clients.md#http-mode).

## Library usage

```ts
import { McpServer } from '@modelcontextprotocol/server';
import { createServer, registerFridaTools, createSessionServer } from 'frida-mobile-mcp';

const server = createServer({ allowCustomScripts: false });      // ready-made McpServer with every tool
// or add the tools to your own server:
const mine = new McpServer({ name: 'my-agent', version: '1.0.0' });
const deviceManager = registerFridaTools(mine, { resources: true, prompts: false });
// or one server per HTTP session:
const perSession = createSessionServer();
```

Also exported: `scriptRegistry`, `DeviceManager`, `composeAgentSource`/`createAgentScript`, `findRemovedApis`, `loadBridgeSource`, `startHttpServer`, `createStdioTransport`, `loadConfig`, `ensureState` and the types (`dist/lib.d.ts`).

## Configuration

Config file `~/.config/frida-mobile-mcp/config.json` (merged over defaults, then CLI flags, then environment):

```json
{
  "allowCustomScripts": false,
  "memoryWriteEnabled": false,
  "allowNativeInjection": false,
  "allowedDevices": [],
  "maxSessions": 4,
  "sessionTimeoutMinutes": 30,
  "maxMessageBuffer": 1000,
  "auditLogPath": "~/.config/frida-mobile-mcp/audit.jsonl",
  "evidence": { "enabled": true, "path": "~/.config/frida-mobile-mcp/evidence", "maxMb": 200, "maxEntries": 5000, "maxEntryKb": 2048 },
  "mobileMcp": { "enabled": true, "command": "npx", "args": ["-y", "@mobilenext/mobile-mcp@latest"] },
  "rateLimits": { "scriptsPerMinute": 10, "memoryReadsPerMinute": 60, "sessionsPerMinute": 5 }
}
```

| Variable | Default | Description |
|----------|---------|-------------|
| `FRIDA_DEVICE_ID` | first USB device | Device to use; same as `--device` |
| `FRIDA_MCP_ALLOW_CUSTOM_SCRIPTS` | unset | `1`/`true` enables `execute_script` and custom `hook_function` bodies; same as `--allow-custom-scripts` |
| `FRIDA_MCP_MEMORY_WRITE` | unset | `1`/`true` enables `write_memory`; same as `--allow-memory-write` |
| `FRIDA_MCP_ALLOW_NATIVE_INJECTION` | unset | `1`/`true` enables `inject_library` (native .so/.dylib injection); a capability separate from custom scripts |
| `FRIDA_MCP_ALLOW_ADB_SHELL` | unset | `1`/`true` enables `adb_shell` (arbitrary device shell commands) |
| `FRIDA_MCP_DEBUG` | unset | `1` enables debug logging on stderr; same as `--debug` |
| `FRIDA_MCP_REMOTE` | unset | `host[:port]` of a frida-server added as a remote device at startup (port 27042); same as `--remote` |
| `FRIDA_MCP_REMOTE_TOKEN` | unset | Auth token of that frida-server (`frida-server --token`); same as `--remote-token` |
| `FRIDA_MCP_REMOTE_CERT` | unset | Path to the PEM certificate of a TLS frida-server (`frida-server --certificate`); same as `--remote-cert` |
| `FRIDA_MCP_HTTP_TOKEN` | unset | Bearer token for the HTTP transport; same as `--http-token` |
| `FRIDA_MCP_SCHEMA_PROFILE` | `full` | `compact` shortens tool schemas for small context windows |
| `FRIDA_MCP_TOOL_PROFILE` | `full` | `core` registers only the core tool set (smaller `tools/list`, e.g. next to REA); also `--tool-profile`. With `FRIDA_MCP_SCHEMA_PROFILE=compact` the catalog drops to 17% of full; see [docs/rea.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/docs/rea.md#4-context-budget) |
| `FRIDA_MCP_TOOLS_EXCLUDE` | (none) | Comma-separated tool-name globs never registered, e.g. `adb_*,frida_server_*` when REA's ADB tools handle the device; also `--exclude-tools`. `get_status` reports the count as `hidden_tools` |
| `FRIDA_MCP_MAX_RESPONSE_CHARS` | `25000` | Truncation limit for a single tool response |
| `FRIDA_MCP_RUNTIME` | Frida default | `qjs` or `v8` script runtime for injected agents |
| `FRIDA_MCP_SNAPSHOTS` | unset | `1` pre-warms a per-session V8 snapshot of the bridge bundle (only with `FRIDA_MCP_RUNTIME=v8`); see [docs/clients.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/docs/clients.md#script-snapshots-snapshots--frida_mcp_snapshots) |
| `FRIDA_MCP_EVIDENCE` | `1` | `0` stops persisting tool results to the evidence store; same as config `evidence.enabled` |
| `FRIDA_MCP_EVIDENCE_PATH` | `~/.config/frida-mobile-mcp/evidence` | Evidence store directory (`YYYY-MM-DD/<evidence_id>.json` plus `index.jsonl`, mode 0600) |
| `FRIDA_MCP_EVIDENCE_MAX_MB` | `200` | Size cap of the evidence store; the oldest records are pruned beyond it |
| `FRIDA_MCP_BRIDGES_DIR` | `dist/bridges` | Directory with the bundled `java.js`/`objc.js` bridges |
| `FRIDA_MCP_COMPILER_PROJECT_DIR` | `$TMPDIR/frida-mobile-mcp/compiler-project` | Project dir the Frida Compiler uses for ES module scripts |
| `FRITAP_AGENT_PATH` | unset | Path to a `fritap_agent.js` bundle for `capture_tls` |
| `FRITAP_VERSION` | `v2.5.2` | friTap tag to download when no local agent is found |
| `FRITAP_AGENT_SHA256` | pinned for `v2.5.2` | Bare sha256 of the downloaded friTap agent for the selected `FRITAP_VERSION` tag; a mismatch refuses the bundle |

## Security guardrails

- `execute_script` and custom `hook_function` handler bodies are refused with `CUSTOM_SCRIPTS_DISABLED` unless `allowCustomScripts` is on; prebuilt scripts and typed hook tools never need it.
- `write_memory` is refused with `MEMORY_WRITE_DISABLED` unless `memoryWriteEnabled` is on. Prebuilt scripts that write target memory (e.g. `anti_frida_evasion` with `mode=spoof`) and `watch_loads` with `spoof=true` are gated the same way.
- `inject_library` is refused with `NATIVE_INJECTION_DISABLED` unless `allowNativeInjection` is on — a capability kept separate from `allowCustomScripts` so native code injection can be withheld even when JS agents are permitted.
- `allowedDevices` restricts which device IDs may be used (empty = any).
- Rate limits per minute for script loads, memory reads/scans and attach/spawn (`RATE_LIMIT_EXCEEDED`, retryable); `maxSessions` and `sessionTimeoutMinutes` cap concurrent and idle sessions.
- Every tool call is appended to the JSONL audit log at `auditLogPath` with its `evidence_id`.
- Every tool result (including memory dumps' metadata, read memory and found secrets) is persisted under the evidence path (`evidence.path`, default `~/.config/frida-mobile-mcp/evidence`) with mode 0600; opt out with `FRIDA_MCP_EVIDENCE=0`.
- `dump_module_memory` only writes under the current directory, the OS temp directory or `~/.config/frida-mobile-mcp/dumps`.
- HTTP transport: loopback bind by default, token required off-loopback, Host/Origin validation.

See [SECURITY.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/SECURITY.md) for reporting vulnerabilities.

## Troubleshooting

- **Version mismatch** (`unable to connect to remote frida-server`, protocol/"unexpected message" errors, timeouts while `adb devices` works): frida-server on the device must be 17.x matching frida-node. Run `frida-mobile-mcp doctor`, then push the matching release (see Requirements).
- **"Timeout was reached" / app killed after spawn**: Android kills a spawned app that stays suspended for more than ~10 s (Frida >= 17.6 cannot disable the launch timeout). `explore_app` resumes before class enumeration for this reason; with `spawn_process`, call `resume_process` promptly. If spawning is slow, launch the app first and attach (`spawn: false` / `attach_process`).
- **No Java messages right after hooking**: Java hooks install inside `Java.perform`, which runs once the ART VM is up. Poll `get_messages` again after a few seconds. "Java is not available" means a native-only process; use `hook_function`, `enumerate_exports` or `analyze_native_function`.
- **`Frida java bridge bundle not found`**: run `npm run build:bridges` (part of `npm run build` and `pretest`) or point `FRIDA_MCP_BRIDGES_DIR` at a directory with `java.js`/`objc.js`.
- **`npm install` fails downloading the frida prebuild**: the `frida` package fetches its native binding in an install script; make sure install scripts are allowed (`npm ci --foreground-scripts` shows the download) and GitHub releases are reachable.
- **Two devices attached**: set `FRIDA_DEVICE_ID`/`--device`, pass `device` to the tool, or `select_device`; with `allowedDevices` set an unlisted device yields `DEVICE_NOT_FOUND`.
- **`SESSION_LOST` / "script destroyed"**: the app crashed or was detached; `get_status` shows `recent_detaches`. Re-running the hook tool creates a fresh session; frequent crashes right after hooking point to anti-Frida checks (`root_jailbreak_bypass`, `capture_tls({ anti_root: true })`).
- **`FRITAP_AGENT_UNAVAILABLE`**: `pip install friTap`, set `FRITAP_AGENT_PATH`, or allow the download (`allow_download: true`).

## Development

```bash
npm ci --foreground-scripts   # installs deps and the frida prebuild
npm run build                 # build:bridges (rollup bundles of the Java/ObjC bridges) + tsc
npm run lint                  # tsc --noEmit
npm test                      # vitest (pretest rebuilds the bridges); device suites are skipped
npm run dev                   # tsc --watch
```

Device end-to-end tests opt in through environment variables:

```bash
FRIDA_MCP_E2E_DEVICE=emulator-5556 FRIDA_MCP_E2E_TARGET=com.example.rc4demo npx vitest run test/e2e
FRIDA_MCP_E2E_DEVICE=emulator-5556 npx vitest run test/fritap/capture-tls.e2e.test.ts
```

The older `FRIDA_E2E=1`, `FRIDA_DEVICE_ID` and `FRIDA_E2E_TARGET` names still work for the `capture_tls` test.

Commits follow Conventional Commits (`feat:`, `fix:`, `docs:`, ...); release-please opens the release PR, maintains `CHANGELOG.md` and the `publish` job in `release.yml` publishes to npm via OIDC trusted publishing. See [CONTRIBUTING.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/CONTRIBUTING.md) and [AGENTS.md](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/AGENTS.md).

## License

[MIT](https://github.com/monkeywave/frida-mobile-mcp/blob/HEAD/LICENSE)