Frida Mobile MCP Server

frida-mobile-mcp

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.

Quick start

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

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

Claude Desktop (claude_desktop_config.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. 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

  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

Tier 2: advanced primitives

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

Address notation and evidence envelope

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

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; the agent workflow around them is in 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.

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

HTTP transport

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.

Library usage

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

{
  "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 }
}

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

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:

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 and AGENTS.md.

License

MIT