frida-mcp

TypeScript MCP server for Frida 17 dynamic instrumentation. Provides ~62 tools and 15 resources for attaching to processes, executing scripts, hooking native and Java methods, bypassing SSL pinning and root detection, reading/writing memory, inspecting Java heaps, exporting large captures to disk, pulling APKs and decompiling them with jadx, and searching Frida 17 API documentation — all through the Model Context Protocol.

What's new in 1.1.0

• Bootstrap: one-call ensure_frida_server (arch-detect + download + push + launch) and spawn_and_instrument (atomic spawn → attach → load → resume) that beats the Android ActivityManagerService 10s timeout.
• Recipe library: parameterised hook templates for OkHttp, Java method, native export, class trace, Mac.doFinal, SSL pinning bypass and root-detection bypass. Recipes install asynchronously so script.load() returns in <100ms; subscribe on recipe.installed via subscribe_messages.
• Source-side filter: every recipe accepts a where predicate evaluated in the agent (host-side blocklist against loops/eval/Function + 50ms agent watchdog), plus a global set_session_filter.
• Static analysis bridge: apk_pull, apk_manifest, decompile_class, decompile_method, list_native_exports, process_inventory, source_jump close the loop between a captured runtime stack frame and the decompiled .java.
• Anti-detection helpers: check_frida_detection enumerates against RootBeer / SafetyNet / Play Integrity / Xposed; bypass_root_detection is opt-in.
• Real fixes to existing tools: list_classes and dump_class now return data on Frida 17.9.x (object-callback Java.enumerateLoadedClasses + Promise-aware execution wrapper); trace_class_methods no longer infinite-recurses (closure-captured overload pattern); session detach now unloads scripts; subscribe_messages long-poll cannot leak listeners.

See CHANGELOG.md for the full list.

Setup

Quick install (Claude Code)

claude mcp add frida-mcp -- npx -y frida-mcp@latest

Installs frida-mcp as an MCP server over stdio. Auto-updates on every Claude Code restart.

Scopes:

# Per-user (available in all projects)
claude mcp add --scope user frida-mcp -- npx -y frida-mcp@latest

# Per-project (shared via .mcp.json, commit to repo)
claude mcp add --scope project frida-mcp -- npx -y frida-mcp@latest

Manual .mcp.json config

{
  "mcpServers": {
    "frida": {
      "command": "npx",
      "args": ["-y", "frida-mcp@latest"]
    }
  }
}

From source (development)

npm install
npm run fetch-docs   # build docs index (optional but recommended)
npm run build
npm start

Then point .mcp.json at the local build:

{
  "mcpServers": {
    "frida": {
      "command": "node",
      "args": ["/path/to/frida-mcp/dist/index.js"]
    }
  }
}

Restart Claude Code to pick up the new server.

Prerequisites

• Node.js 20+
• Frida 17 (npm install frida@17)
• A USB-connected device (Android phone) for on-device operations
• frida-server running on the target device

Tool Reference

Device Tools (4)

Tool	Description	Key Params
enumerate_devices	List all Frida-visible devices (local, USB, remote)	—
get_device	Get a specific device by ID	device_id
get_usb_device	Get the USB-connected device	—
get_local_device	Get the local (host) device	—

Process Tools (6)

Tool	Description	Key Params
enumerate_processes	List all running processes	device_id?
get_process_by_name	Find process by name (case-insensitive substring)	name, device_id?
attach_to_process	Lightweight attach check	pid, device_id?
spawn_process	Spawn a new process	program, args?, device_id?
resume_process	Resume a spawned/suspended process	pid, device_id?
kill_process	Kill a process	pid, device_id?

Session Tools (5)

Tool	Description	Key Params
create_interactive_session	Attach and create a managed session (spawn fallback is opt-in)	process_id, device_id?, spawn_fallback?, app_identifier?, auto_resume_spawned?
execute_in_session	Execute JS in session (transient or persistent)	session_id, javascript_code, keep_alive?
get_session_messages	Retrieve queued messages with pagination (previews; blobs for large fields)	session_id, limit?, offset?, clear_mode?
read_session_message_blob	Read an offloaded message blob (payload/data) in bounded chunks	session_id, blob_id, offset?, limit?, encoding?
get_archived_session_messages	List archived messages that were cleared/evicted from memory	session_id, limit?, offset?

Script Management Tools (4)

Tool	Description	Key Params
load_script	Load JS file from disk, auto-detect RPC exports	session_id, file_path, script_id?
list_scripts	List loaded scripts with metadata	session_id
unload_script	Unload a script	session_id, script_id
call_rpc_export	Call an RPC-exported method	session_id, script_id, method, args?

Beginner: load_script vs call_rpc_export

If you are new to Frida, think about this in two layers:

• load_script: put your agent code inside the target app and keep it running.
• call_rpc_export: call one function from that already-loaded agent.

Simple rule:

• You usually call load_script once.
• You can call call_rpc_export many times after that.
• When finished, call unload_script.
• Use export_capture_bundle instead when the result size is unknown or you want a host-side file for later analysis.

Minimal flow:

1) create_interactive_session(...)  -> session_id
2) load_script(session_id, "agent.js") -> script_id
3) call_rpc_export(session_id, script_id, "methodName", [...args]) -> result
4) unload_script(session_id, script_id)

Export Tools (1)

Tool	Description	Key Params
export_capture_bundle	Export RPC output and captured messages to a disk JSONL bundle (token-safe summary response)	session_id, rpc?, include_messages?, include_archived_messages?, clear_mode?, output_path?, format?, response_detail?

export_capture_bundle is the preferred path for large or unbounded output. By default it returns a slim path_only response and writes the full capture to disk on the host machine.

Memory Tools (6)

Tool	Description	Key Params
list_modules	List loaded native modules	session_id
find_module	Find module by name	session_id, name
list_exports	List exported symbols from a module	session_id, module_name
read_memory	Hex dump at address (supports module+0xoffset)	session_id, address, size?
write_memory	Write bytes to address (auto memory protection)	session_id, address, hex_bytes
search_memory	Search readable memory for hex/string patterns	session_id, pattern, pattern_type?, max_results?

Java Tools (6)

Tool	Description	Key Params
list_classes	Enumerate loaded Java classes (max 500)	session_id, filter?
find_instances	Find live heap instances via Java.choose()	session_id, class_name, max_instances?
list_methods	List all methods of a Java class with types/modifiers	session_id, class_name
dump_class	Full class introspection (methods, fields, constructors, interfaces, superclass)	session_id, class_name
run_java	Execute arbitrary code inside Java.perform()	session_id, code
android_hook_method	Hook a Java method (all overloads), log args/retval/backtrace	session_id, class_name, method_name, log_args?, log_retval?, log_backtrace?

Native Hook Tools (2)

Tool	Description	Key Params
hook_function	Install persistent Interceptor.attach hook	session_id, address, log_args?, log_retval?, num_args?
get_backtrace	One-shot backtrace capture (self-detaches)	session_id, address, style?

Android Tools (6)

Tool	Description	Key Params
android_ssl_pinning_disable	Bypass SSL pinning (TrustManager, SSLContext, OkHttp, TrustManagerImpl)	session_id, script_id?
android_get_current_activity	Get foreground activity via ActivityThread reflection	session_id
list_apps	List installed applications (identifier, name, PID)	device_id?
android_check_frida_server	Check Android frida-server health (running instances, version mismatch warnings)	device_id?, adb_serial?
file_ls	List directory contents on target device (Java File API)	session_id, path
file_read	Read a text file from target device	session_id, path, max_size?

Documentation Tools (1)

Tool	Description	Key Params
search_frida_docs	Full-text search Frida 17 API docs (size-safe paginated snippets)	query, limit?, offset?, snippet_chars?

Bootstrap Tools (2)

Tool	Description	Key Params
ensure_frida_server	Detect device arch, download (opt-in) matching frida-server from GitHub releases, push to device, kill old instances, launch detached, verify reachable. Subsumes the 6-command manual install.	device_id?, target_version?, binary_path?, allow_network? (default false), force_redownload?, verify_timeout_ms?
spawn_and_instrument	Atomically device.spawn → device.attach → optional script.load → device.resume inside a single MCP call so AMS's ~10s "failed to attach" window cannot fire between steps.	package, device_id?, script_path?, argv?, resume?

Recipe Tools (8)

Vetted, parameterised hook templates so you do not have to write 100+ lines of Frida JS for every common task. All recipes defer their hook installation via Script.nextTick so script.load() returns immediately; long-poll subscribe_messages on the recipe.installed event to wait for hooks to be live. All recipes accept a where predicate that gates send() in the agent.

Tool	Description	Key Params
hook_okhttp_requests	Snoop every finalized okhttp3.Request$Builder.build across all OkHttp clients.	session_id, url_includes?, include_stack?, include_body?, max_body_bytes?, where?
hook_java_method_recipe	Hook all overloads of a Java method with source-side where, max_emits cap, and per-string truncation.	session_id, class_name, method_name, log_args?, log_retval?, log_backtrace?, max_emits?, truncate_at?, where?
hook_native_export	Interceptor.attach to a single exported symbol via Process.getModuleByName().getExportByName().	session_id, module, symbol, num_args?, decode_ret_as_cstring?, where?
trace_class_methods	frida-trace -j 'pkg.*!*' equivalent: enumerate matching classes, install lightweight call-tracers. Skips native / synthetic / $$Lambda to avoid agent crashes.	session_id, class_filter, method_filter?, max_methods?, where?
dump_mac_doFinal	Hook both overloads of javax.crypto.Mac.doFinal. Generic crypto observer — cracks HMAC algorithms in seconds.	session_id, include_input?, where?
bypass_ssl_pinning	TrustAllCerts + null hostname verifier + OkHttp3 CertificatePinner + Conscrypt TrustManagerImpl.	session_id
search_recipes	Free-text search the local recipe registry.	query
describe_recipe	Return parameter schema + emitted event types for a recipe by slug.	slug

Plus two helpers wired through the same machinery:

Tool	Description	Key Params
set_session_filter	Install / clear a global JS predicate that gates every recipe's send() before its per-recipe where runs.	session_id, predicate_js
subscribe_messages	Long-poll for new session messages. Resolves as soon as N matching messages exist or after timeout_ms. Optional where is a JS predicate over the stored message; consume=true removes returned messages from the queue.	session_id, where?, min_count?, timeout_ms?, consume?, since_seq?

Static Analysis Tools (7)

Bridge between Frida's runtime view and the APK's static source. Shell out to adb, aapt2, jadx, nm / readelf.

Tool	Description	Key Params
apk_pull	pm path + adb pull an installed APK into ~/.cache/frida-mcp/apks/. Cached.	package, device_id?, force?
apk_manifest	aapt2 dump xmltree → JSON (package, versions, permissions, exported components).	apk_path
decompile_class	jadx full-class decompile (cached per APK fingerprint). Inner classes via outer file.	apk_path, fqcn
decompile_method	Slice one method out of the decompiled class. Skips @kotlin.Metadata block; falls back to full_class if name is inlined.	apk_path, fqcn, method
list_native_exports	nm -D --demangle (or readelf -sDW) parser for a .so's exported symbols.	so_path, tool?, filter?
process_inventory	One-shot: loaded native modules + user-namespace Java classes + detected networking stack(s) + anti-detection-lib hits.	session_id
source_jump	Parse a Java stack trace and return a ±context_lines snippet around each user frame in the decompiled source. Falls back to class <Name> declaration when method name not found.	stack_trace, apk_path, context_lines?, include_framework_frames?, max_frames?

Anti-Detection Tools (2)

Tool	Description	Key Params
check_frida_detection	Enumerate loaded classes against known detection-lib patterns (RootBeer, SafetyNet, Play Integrity, Xposed, plus keyword Frida/Magisk/Substrate). Recommends matching bypass recipe slugs.	session_id
bypass_root_detection	Opt-in: patch File.exists for su paths, Runtime.exec("su"), Build.TAGS test-keys. Derivative of @dzonerzy/fridantiroot + objection's root-bypass agent.	session_id, where?

Resources

URI	Description
frida://version	Installed Frida version
frida://processes	USB device process list
frida://devices	All available devices
frida://docs/index	Documentation section listing
frida://docs/{section_id}	Individual doc section (11 sections)

Architecture

src/
├── index.ts                  # Entry point — McpServer + StdioServerTransport
├── state.ts                  # SessionManager singleton (sessions, scripts, messages)
├── utils.ts                  # resolveDevice, resolveAddressJS, wrapForExecution,
│                             #   executeTransientScript, truncateResult
├── resources.ts              # MCP resources (runtime + docs)
├── docs/
│   ├── index.ts              # DocStore — search/scoring over frida-api.json
│   └── frida-api.json        # Pre-parsed Frida 17 API documentation
├── injected/
│   ├── helpers.ts            # Frida 17-safe JS generators (modules, memory read/write/search)
│   ├── java-helpers.ts       # Java introspection, hooking, SSL bypass, file ops JS generators
│   └── hook-templates.ts     # Native hook JS generators
└── tools/
    ├── device.ts             # Device enumeration (4 tools)
    ├── process.ts            # Process management (6 tools)
    ├── session.ts            # Session management (5 tools)
    ├── script-mgmt.ts        # Script loading/RPC (4 tools)
    ├── export.ts             # One-shot RPC + capture export (1 tool)
    ├── memory.ts             # Module/memory operations (6 tools)
    ├── java.ts               # Java introspection & hooking (6 tools)
    ├── native-hooks.ts       # Native hooking (2 tools)
    ├── android.ts            # Android pentesting & file ops (5 tools)
    └── docs.ts               # Doc search (1 tool)

Key Patterns

SessionManager — Unified state for all sessions, scripts, and messages. Replaces the Python server's 4 separate global dicts. Message queue is capped at 1000 to prevent unbounded memory growth; cleared/evicted messages are archived to disk as lightweight summaries, and large payload/data fields are offloaded to disk with blob references to keep tool output token-safe.

Injected JS generators — Template functions that produce Frida 17-compliant JavaScript. Rules: var (not const/let), no arrow functions, instance methods on NativePointer (not Memory.readX), Process.getModuleByName (not Module.*).

Promise-based execution — executeTransientScript uses Promise-based message collection instead of time.sleep(). Scripts send an execution_receipt message and are auto-unloaded after.

Output truncation — truncateResult() binary-searches for the max array items that fit within 24KB to stay under MCP's token limit. Applied to enumerate_processes, list_modules, list_exports, list_classes, get_session_messages, and read_session_message_blob.

Usage Examples

Attach and execute code

1. enumerate_processes → find target PID
2. create_interactive_session(pid) → get session_id
3. execute_in_session(session_id, "Process.arch") → "arm64"

Load a script and call RPC

1. create_interactive_session(pid) → session_id
2. load_script(session_id, "my_script.js") → detects rpc.exports: ["doStuff"]
3. call_rpc_export(session_id, script_id, "doStuff", [arg1, arg2]) → result

Hook a native function

1. create_interactive_session(pid) → session_id
2. hook_function(session_id, "libnative.so+0x1234", log_args=true, num_args=4) → hook_id
3. (trigger the function on device)
4. get_session_messages(session_id) → hook arg/retval logs

One-step RPC + capture export to disk

1. create_interactive_session(pid) → session_id
2. load_script(session_id, "/path/hook.js") → script_id
3. export_capture_bundle(
     session_id,
     rpc={script_id, method:"getSignings"},
     include_messages=true,
     clear_mode="returned",
     response_detail="path_only"
   ) → output_path + slim summaries

Hook a Java method

1. create_interactive_session(pid) → session_id
2. list_classes(session_id, filter="com.example") → find target class
3. list_methods(session_id, "com.example.ApiClient") → find target method
4. android_hook_method(session_id, "com.example.ApiClient", "sendRequest") → hook_id
5. (trigger the method on device)
6. get_session_messages(session_id) → method args/retval logs

Bypass SSL pinning

1. create_interactive_session(pid) → session_id
2. android_ssl_pinning_disable(session_id) → script_id
3. get_session_messages(session_id) → list of bypassed targets

Search and patch memory

1. create_interactive_session(pid) → session_id
2. search_memory(session_id, pattern="secret_key", pattern_type="string") → addresses
3. read_memory(session_id, "0x7f1234") → hex dump
4. write_memory(session_id, "0x7f1234", "00 00 00 00") → bytes written

Browse files on target device

1. create_interactive_session(pid) → session_id
2. file_ls(session_id, "/data/data/com.example.app") → directory listing
3. file_read(session_id, "/data/data/com.example.app/shared_prefs/config.xml") → file content

Search Frida 17 docs

1. search_frida_docs("Module.findExportByName") → migration guide ranked first
2. search_frida_docs("Interceptor.attach") → instrumentation section with examples
3. search_frida_docs("Java.perform", limit=3, offset=3) → next page of snippet results

Frida 17 Notes

This server is built for Frida 17 compatibility. Key differences from older Frida versions:

• No Module.findExportByName() — Use Process.getModuleByName(name).findExportByName(sym) instead
• No Memory.readX() static methods — Use NativePointer instance methods: ptr(addr).readU32()
• No enumerateXSync() methods — Use Process.enumerateModules(), module.enumerateExports()
• var instead of const/let in injected scripts — Avoids issues with Frida's V8 runtime in some contexts
• Java bridge moved in Frida 17 — Java-capable tools compile scripts with frida-java-bridge and inject globalThis.Java before running user code

The search_frida_docs tool automatically boosts the migration guide when you query deprecated API names.

Operational Skill (Recommended)

For reliable Frida MCP operation (Frida 17), use the companion skills repository: https://github.com/yfe404/frida-mcp-skills.

The frida-mcp-workflow skill enforces a strict workflow: Idea -> Scripting -> Execution -> Notes. It also enforces docs-first usage, file-based scripts over large inline payloads, and script lifecycle hygiene (track/unload scripts to avoid duplicate hooks on the same target).

Development

# Build
npm run build

# Run all tests (unit + integration)
npm test

# Run only unit tests
npm run test:unit

# Run only integration tests
npm run test:integration

# Run device tests (requires USB device with frida-server)
npm run test:device

# Fetch/update Frida API docs
npm run fetch-docs

Test Structure

test/
├── unit/              # 137 tests — pure logic, no device needed
│   ├── utils.test.ts
│   ├── injected-helpers.test.ts
│   ├── injected-java.test.ts
│   ├── injected-hooks.test.ts
│   ├── session-manager.test.ts
│   └── doc-store.test.ts
├── integration/       # 12 tests — MCP server via InMemoryTransport + stdio
│   ├── mcp-server.test.ts
│   └── stdio-smoke.test.ts
├── device/            # 5 tests — auto-skip when no USB device
│   └── device-smoke.test.ts
└── fixtures/
    └── frida-api-fixture.json

License

MIT