Frida Mobile MCP

frida-mobile-mcp

一个 MCP 服务，通过 Frida 17 为 AI Agent 提供 Android 和 iOS 应用的动态插桩能力。它提供 40 个工具：高级工具可为你管理设备、会话和脚本（探索应用、Hook Java/ObjC/原生方法、跟踪调用、绕过 SSL Pinning、使用 friTap 捕获 TLS 密钥和明文、运行预构建分析脚本、验证自定义脚本），以及底层原语（启动/附加、枚举模块和符号、解析地址、控制流分析、内存转储）。地址采用与 Ghidra/IDA 相同的 module+0xoffset 表示法，因此结果可在静态和动态工具之间直接迁移，无需转换；每个结果都附带证据封装（evidence_id、limitations、coverage）。可选的 UI 自动化通过 mobile-mcp 实现。

快速开始

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)

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

各客户端的说明、HTTP 模式和远程 frida-server 配置见 docs/clients.md。仓库中还包含 Claude Desktop 扩展清单（manifest.json，MCPB）和 MCP 注册表条目（server.json）。

要求

• Node.js >= 22.12（CI 在 Linux、macOS 和 Windows 上运行 22 和 24 版本）。npm install 会运行 frida 包的安装脚本，下载原生 frida-node 预构建文件。

• 运行 frida-server 17.x 的设备或模拟器。此软件包依赖 frida-node ^17.24.3；设备上的 frida-server 必须具有相同的主版本（17），并且最好具有相同的次版本。frida-mobile-mcp doctor 会输出两个版本并标记不匹配项。

• Android：从 https://github.com/frida/frida/releases 下载匹配的 frida-server-17.x.y-android-<arch>.xz，然后

  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：已越狱且安装了来自 Frida Cydia/Sileo 软件源的匹配 Frida 软件包的设备。未越狱的设备需要重新打包应用并加入 Frida Gadget；之后，服务端会像附加到其他进程一样，附加到启用了 Gadget 的进程。

• 可选：为 capture_tls 执行 pip install friTap（否则会在首次使用时下载固定版本的 Agent），并确保首次执行 mobile_action 时可访问网络，以运行 npx -y @mobilenext/mobile-mcp@latest。

Frida 17 的新增内容

• 内置 Bridge。 Frida 17 不再随 GumJS 运行时提供 Java/ObjC Bridge。npm run build:bridges 会将 frida-java-bridge 和 frida-objc-bridge 打包到 dist/bridges/{java,objc}.js；服务端会根据平台，在每个脚本运行前注入相应的 Bridge（Android 使用 Java，iOS/macOS 使用 ObjC）。
• 旧版脚本仍可运行。 execute_script 通过 Script.evaluate 运行经典（非模块）脚本，因此为 Frida 16 编写的 Java.perform(...) 脚本无需修改即可运行，并且错误中保留其原始行号。ES 模块（import Java from "frida-java-bridge"，JS 或 TS）会在主机上使用 Frida Compiler 编译；frida-compile 打包的内容（以 📦 标记开头）则会按原样加载。
• 已移除的 API 会进行检查。 validate_script 会标记在 Frida 17 中会报错的静态 Module.findExportByName/findBaseAddress/enumerateExports、Memory.readX/writeX 和 *Sync 枚举器，并建议改用 Module 实例或 NativePointer。生成的脚本会从 Agent 前置代码中获取 findExport(lib, name) 和 hookNative(lib, name, callbacks) 辅助函数，并通过 __FRIDA_MCP__.options 获取模板选项。
• analyze_native_function 使用 Process.findFunctionRange 和 Frida 17.12+ 的 ControlFlowGraph（如果不可用，则回退到线性反汇编，并在 limitations 中注明）。

工具参考

第 1 层：高级工具

工具	描述
get_status	已连接的设备、活动会话（平台、脚本数量、最近活动）、钩子、跟踪记录，以及最近的分离/崩溃情况。会话丢失后，首次运行时也应调用此工具。
frida_help	主题帮助：概览、钩子、跟踪、内存、脚本、原生、tls、移动端、示例、高级、script_catalog。
detect_app_technologies	识别库、框架和安全机制；返回推荐的脚本目标。
explore_app	以挂起状态启动应用、插桩并恢复运行；返回 pid、平台、模块和筛选后的类列表。
search_classes_and_methods	在运行中的应用内对类进行正则搜索（使用 include_methods 时也搜索方法）。
hook_method	为 Java（com.example.Class.method）、ObjC（-[Class sel:]）或原生目标（libssl.so!SSL_read、libfoo.so+0x1234、0x7f...、!open）设置钩子，并自动管理会话；回溯格式为 module+0xoff (symbol)。
trace_method	在指定时长内，按 glob 模式（com.example.net.*、-[NSURL*]、libssl.so!SSL_*）进行类似 frida-trace 的跟踪。
execute_script	运行自定义脚本：经典 JS（注入桥接）、ES 模块 JS/TS（使用 Frida Compiler 编译）或 frida-compile 包。timeout_ms 限制初始运行时长。需要启用 allowCustomScripts。
validate_script	无需设备即可检查语法、类型和 Frida 17 中已移除的 API。请在使用 execute_script 前调用。
run_prebuilt_script	运行下方列出的 8 个预构建脚本；不传入 script_name 时会列出这些脚本。
bypass_ssl_pinning	一键绕过证书绑定（Android：TrustManager、OkHttp CertificatePinner、Conscrypt；iOS：SecTrust、ATS、BoringSSL）。
capture_tls	friTap：捕获 TLS 会话密钥（NSS 密钥日志），并可选择为 OpenSSL/BoringSSL、Conscrypt、NSS、GnuTLS、wolfSSL、mbedTLS、Secure Transport 等获取解密后的明文/合成 pcap。
read_memory	以任意地址表示法读取最多 4 MB 内存；返回十六进制内容以及绝对地址和 module+offset。
write_memory	将十六进制字节写入内存。除非启用 memoryWriteEnabled，否则此功能处于禁用状态。
scan_memory	扫描字节模式（48 89 5c 24 ?? 57），也可限制在指定模块内。
get_messages	获取缓冲的钩子调用、跟踪命中、send() 输出和错误；使用 since 分页。
stop_instrumentation	移除目标上的所有钩子、脚本和跟踪，并断开连接。
unload_script	从会话中卸载单个脚本（钩子、跟踪或自定义脚本），同时保持连接。
mobile_action	mobile-mcp UI 自动化的入口（截图、元素、点击、滑动、输入、启动应用、列出应用）。

第 2 层：高级基础功能

工具	描述
list_devices	本地、USB 和远程 Frida 设备（frida-ls-devices）。
select_device	按 ID、类型或远程主机选择活动设备。
get_device_info	操作系统版本、架构和系统参数。
list_processes	正在运行的进程（frida-ps）。
list_applications	已安装和正在运行的应用程序。
get_frontmost_application	前台应用程序。
spawn_process	以挂起状态启动，以便进行早期插桩；使用 resume_process 恢复。
attach_process	按 PID 或名称附加到正在运行的进程。
resume_process	恢复已挂起的进程。
kill_process	终止进程。
detach_session	分离会话并卸载其脚本。
list_sessions	此服务管理的会话。
enumerate_modules	已加载的模块，包含名称、基址、结束地址、大小和路径；支持正则表达式 filter。
enumerate_exports	模块的导出项，支持分页。
enumerate_imports	模块的导入项，包含提供模块的信息，支持分页。
enumerate_symbols	符号，包括非导出符号和调试符号；在 Agent 内支持正则表达式筛选和分页（Linux、Android、iOS、macOS）。
resolve_address	将 0x7f... 转换为 module+0xoffset（以及最近的符号），并将 module+0xoff / module!sym 转换为绝对地址。
analyze_native_function	函数范围、基本块和边、首批指令；地址格式为绝对地址和 module+0xoffset。
dump_module_memory	将模块基址相对内存转储到主机文件（位于 cwd、临时目录或 ~/.config/frida-mobile-mcp/dumps），以便原始导入到 Ghidra/IDA。
list_threads	线程信息，包含 ID、名称、状态、当前 pc（格式为 module+0xoffset）；可选 8 帧回溯。
hook_function	在 session_id 上设置底层 Interceptor 钩子，可选自定义 on_enter / on_leave 代码体（自定义代码体需要 allowCustomScripts）。
unhook_function	按 ID 移除钩子。

mobile_action 网关

mobile_action({ action, params }) 会转发到按需启动的 mobile-mcp 进程（默认使用 npx -y @mobilenext/mobile-mcp@latest，可通过 mobileMcp 配置，使用 --no-mobile-mcp 禁用）。不带 action 调用即可列出可用操作。所有 Frida 工具均可独立使用；如果无法启动，错误为 MOBILE_MCP_UNAVAILABLE。

此服务还会公开 frida:// 资源（版本、设备、进程、应用、会话、消息、脚本目录）和三个工作流提示词（explore_app、security_audit、trace_functionality）。

预置脚本

脚本	用途
ssl_pinning_bypass	绕过证书固定（TrustManager、OkHttp、Conscrypt、WebView；SecTrust、ATS、BoringSSL、AFNetworking）
root_jailbreak_bypass	绕过 root/越狱检测（Java、SystemProperties、原生 fopen/access/stat、canOpenURL、sysctl）
class_enumeration	列出已加载的 Java/ObjC 类并支持正则表达式筛选；可选显示方法
method_hook	通用方法钩子（Java/ObjC 方法或原生 target），记录参数和返回值
crypto_monitor	监控 javax.crypto、CommonCrypto 和 OpenSSL 调用
network_inspector	监控套接字、DNS、UDP 和 TLS SSL_read/SSL_write（使用 log_data 记录明文数据）
keychain_prefs	访问 iOS Keychain 和 Android SharedPreferences
filesystem_monitor	文件 I/O 和 SQLite

地址表示法与证据封装

所有接收或返回原生地址的工具都使用同一套表示法：

形式	含义	示例
module!symbol	导出符号或 ELF/Mach-O 符号	libssl.so!SSL_write
module+0xOFFSET	相对于模块基址的偏移（Ghidra/IDA RVA）；也接受十进制形式 libfoo.so+4660	libfoo.so+0x1a2b0
0xADDRESS	运行时绝对地址	0x7f3a1c2b1234
symbol / !symbol	在所有模块中搜索的全局导出符号	!open

结果优先使用 module+0xoffset，以便静态工具在映像基址 + 偏移处反编译；绝对地址仅在地址不属于已知模块时出现，并附带一项 limitations。

每次成功调用都会返回 result、evidence_id（UUID，也会写入审计日志）、limitations[]、coverage（complete | unknown）、session_context 和 suggested_next。错误会包含 code、category、retryable、remediation 和 recovery_actions。字段语义和错误代码表见 docs/interop.md；围绕这些内容的 Agent 工作流见 skills/mobile-dynamic-analysis/SKILL.md。

与静态工具配合使用

frida-mobile-mcp 专为与 ReVa（Ghidra）、ida-pro-mcp（IDA Pro）和 REA 协同运行而构建：静态工具负责回答代码表达了什么，本服务负责回答代码在运行时做了什么。静态工具找到 libfoo.so+0x1234 后，hook_method 或 analyze_native_function 可直接接收该字符串；回溯和 resolve_address 会以相同格式返回偏移，供反编译使用。enumerate_modules 会返回 base/end，用于重定位 Ghidra/IDA 项目；dump_module_memory 会为解包后的库写入一个相对于基址的映像，以便直接导入；capture_tls 则会显示静态分析找到的封装函数实际在线路上发送的字节。三服务客户端配置以及完整的静态 → 动态 → 静态流程演示见 docs/interop.md。

HTTP 传输

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

位于 /mcp 的 Streamable HTTP 端点为每个客户端创建一个 MCP 会话（Mcp-Session-Id）；携带该标头的 DELETE /mcp 请求会结束会话。服务默认绑定到环回地址；当 --host 不是环回地址时，必须提供 Bearer 令牌（--http-token 或 FRIDA_MCP_HTTP_TOKEN），否则服务会拒绝启动。系统会验证 Host 和 Origin 标头是否与绑定主机匹配（防止 DNS 重绑定）。此服务不支持 TLS；跨网络使用时，请通过反向代理或 SSH 隧道连接。--port 0 会选择一个空闲端口；绑定的 URL 会作为 JSON 行输出到 stderr。完整的 curl 示例见：docs/clients.md。

库用法

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();

另有导出：scriptRegistry、DeviceManager、composeAgentSource/createAgentScript、findRemovedApis、loadBridgeSource、startHttpServer、createStdioTransport、loadConfig、ensureState 和各类类型（dist/lib.d.ts）。

配置

配置文件 ~/.config/frida-mobile-mcp/config.json（在默认值基础上合并，然后应用 CLI 标志，最后应用环境变量）：

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

变量	默认值	描述
FRIDA_DEVICE_ID	第一个 USB 设备	要使用的设备；与 --device 相同
FRIDA_MCP_ALLOW_CUSTOM_SCRIPTS	未设置	1/true 启用 execute_script 和自定义 hook_function 函数体；与 --allow-custom-scripts 相同
FRIDA_MCP_MEMORY_WRITE	未设置	1/true 启用 write_memory；与 --allow-memory-write 相同
FRIDA_MCP_DEBUG	未设置	1 启用向 stderr 输出调试日志；与 --debug 相同
FRIDA_MCP_REMOTE	未设置	启动时作为远程设备添加的 frida-server 的 host[:port]（端口 27042）
FRIDA_MCP_HTTP_TOKEN	未设置	HTTP 传输的 Bearer token；与 --http-token 相同
FRIDA_MCP_SCHEMA_PROFILE	full	compact 可缩短工具架构，以适应较小的上下文窗口
FRIDA_MCP_MAX_RESPONSE_CHARS	25000	单个工具响应的截断上限
FRIDA_MCP_RUNTIME	Frida 默认值	注入 Agent 的脚本运行时：qjs 或 v8
FRIDA_MCP_BRIDGES_DIR	dist/bridges	存放捆绑的 java.js/objc.js 桥接文件的目录
FRIDA_MCP_COMPILER_PROJECT_DIR	$TMPDIR/frida-mobile-mcp/compiler-project	Frida Compiler 用于 ES 模块脚本的项目目录
FRITAP_AGENT_PATH	未设置	capture_tls 使用的 fritap_agent.js 包的路径
FRITAP_VERSION	v2.5.2	找不到本地 Agent 时要下载的 friTap 标签

安全防护

• 除非启用了 allowCustomScripts，否则会拒绝 execute_script 和自定义 hook_function 处理程序函数体，并返回 CUSTOM_SCRIPTS_DISABLED；预构建脚本和带类型的钩子工具无需启用此项。
• 除非启用了 memoryWriteEnabled，否则会拒绝 write_memory，并返回 MEMORY_WRITE_DISABLED。
• allowedDevices 用于限制可使用的设备 ID（为空表示不限）。
• 对脚本加载、内存读取/扫描以及附加/生成操作设置每分钟速率限制（超限时返回可重试的 RATE_LIMIT_EXCEEDED）；maxSessions 和 sessionTimeoutMinutes 限制并发会话数和空闲会话时长。
• 每次工具调用都会连同其 evidence_id 追加到 auditLogPath 指定的 JSONL 审计日志中。
• dump_module_memory 只会在当前目录、操作系统临时目录或 ~/.config/frida-mobile-mcp/dumps 下写入文件。
• HTTP 传输：默认绑定到回环地址；非回环地址必须提供令牌，并进行 Host/Origin 验证。

如需报告漏洞，请参阅 SECURITY.md。

故障排查

• 版本不匹配（出现 unable to connect to remote frida-server、协议错误／“unexpected message”错误，或在 adb devices 正常工作时超时）：设备上的 frida-server 必须为与 frida-node 匹配的 17.x 版本。运行 frida-mobile-mcp doctor，然后推送匹配的版本（参见 Requirements）。
• 出现“Timeout was reached”／应用在启动后被杀死：Android 会在启动的应用保持挂起超过约 10 秒后将其杀死（Frida >= 17.6 无法禁用启动超时）。因此，explore_app 会在枚举类之前恢复应用；使用 spawn_process 时，请及时调用 resume_process。如果启动过程较慢，请先启动应用，再附加（spawn: false／attach_process）。
• 挂钩后立即没有 Java 消息：Java 挂钩在 Java.perform 内安装，该方法会在 ART VM 启动后运行。几秒后再次轮询 get_messages。“Java is not available”表示这是一个仅含原生代码的进程；请使用 hook_function、enumerate_exports 或 analyze_native_function。
• Frida java bridge bundle not found：运行 npm run build:bridges（这是 npm run build 和 pretest 的一部分），或将 FRIDA_MCP_BRIDGES_DIR 指向包含 java.js／objc.js 的目录。
• 下载 frida 预构建包时 npm install 失败：frida 包会在安装脚本中获取其原生绑定；请确保允许安装脚本运行（npm ci --foreground-scripts 会显示下载过程），并且可以访问 GitHub releases。
• 连接了两台设备：设置 FRIDA_DEVICE_ID／--device，将 device 传给工具，或使用 select_device；设置 allowedDevices 后，未列出的设备会返回 DEVICE_NOT_FOUND。
• SESSION_LOST／“script destroyed”：应用崩溃或已断开连接；get_status 会显示 recent_detaches。重新运行挂钩工具会创建新的会话；如果挂钩后频繁崩溃，可能是反 Frida 检查导致的（root_jailbreak_bypass、capture_tls({ anti_root: true })）。
• FRITAP_AGENT_UNAVAILABLE：运行 pip install friTap，设置 FRITAP_AGENT_PATH，或允许下载（allow_download: true）。

开发

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

设备端到端测试通过环境变量启用：

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

提交遵循 Conventional Commits（feat:、fix:、docs: 等）；release-please 会创建发布 PR、维护 CHANGELOG.md，而 release.yml 中的 publish 作业会通过 OIDC 可信发布机制发布到 npm。请参阅 CONTRIBUTING.md 和 AGENTS.md。

许可证

MIT