frida-mcp

TypeScript stdio MCP for Frida iOS exploration — Playwright-style loop:

device_list → app_list → session_open → wait_until_texts (TikTok) / wait → screen_snapshot
  → tap(ref) / swipe / type_text → screen_snapshot → … → session_close

If session_open hangs or Cursor cancel leaves MCP half-dead: session_status → session_force_unlock → retry one open. Independent of fleetcontrol (agent JS copied under agent/).

Requirements

Mismatch between host frida and phone frida-server → inject / session_open fails.

Related MCP server: ya-frida-mcp

Device prerequisites

This MCP targets jailbroken iPhones only. Without a jailbreak and a running frida-server, device_list may still show USB, but inject / touch / UI text collection will fail.

1. Supported jailbreak stacks

Not supported: stock (non-jailbroken) devices, Developer Mode alone, pymobiledevice3 without Frida, or remote TCP Frida (USB-only MVP).

2. frida-server must be running on the phone

1. Download frida-server from Frida releases with the same major as the host npm frida package (e.g. host frida@17.16.x → device frida-server 17.x).

2. Push it to the device and chmod +x (paths vary by jailbreak; common: /var/jb/usr/sbin/frida-server or /usr/sbin/frida-server).

3. Start it as root and keep it running, e.g.:

# On-device SSH / terminal (adjust path for your jailbreak)
sudo frida-server -D
# or foreground for debugging:
sudo frida-server

4. Verify from the PC:

pnpm cli call device_list
# or
npx frida-ps -U

Only then start the MCP. If frida-server stops, later session_open calls will fail or hang.

3. Host machine

• Node.js ≥ 22; pnpm install && pnpm build in this repo

• USB cable + trusted computer

• For Photos import: Python with pymobiledevice3, pointed to by FRIDA_MCP_PYTHON

4. TikTok / touch rules

Search UI tip: prefer tool tiktok_open_search from For You (taps the top-right magnifier with retries). The top wide field is the text input ([input]). The narrow 搜尋 / 搜索 / Search label on the right is a submit button (tap after typing) — never smart_type_text it.

Spawn-only (this device stack)

RootHide / TikTok / many jailbreak setups cannot use reliable attach (touch _touchesEvent null, or process dies).

kill old pid → device.spawn(bundleId) suspended → attach(pid) → inject agent → [netEnable?] → resume

Dual parallel: App + SpringBoard (+ Photos side channel)

Stuck open / half-dead MCP: Cursor cancel does not abort server-side Frida. If device_list works but session_open / ping hang forever, check session_status (appLockBusy, appLockWaiters), then call session_force_unlock or restart the MCP process. CLI can still open apps because it is a different Node process with its own locks.

session_open also has a hold timeout (~open+close+5s): if Frida close/spawn hangs but the event loop is alive, the lock is released with APP_LOCK_HOLD_TIMEOUT instead of pinning forever. On hold/open timeout the server best-effort kills inFlightPid / last app pid and sets orphanFridaOpPossible. Soft-close timeout on the app channel also kills that pid (SpringBoard is never killed).

Stuck / orphan recovery: session_status (look for orphanFridaOpPossible / inFlightPid) → session_force_unlock (kills orphan pid, clears flag) → one session_open. Do not immediately re-open while orphan is set.

• Held in parallel — App + SB Frida scripts; Photos is a temporary third channel.

• RPCs concurrent — separate locks; dual_ping / Promise.all([app…, sb…]) run together.

• Not multi-app business — one app + SpringBoard; Photos is import/clear only.

• photos_ never closes TikTok* — spawn Photos may briefly steal foreground.

Media import (PhotoKit, no fleetcontrol HTTP)

Requires Python 3 with pymobiledevice3 on the interpreter MCP actually runs (AFC).
MCP does not pip install for you. Missing deps → stage: afc within ~5s (preflight), not a 120s hang.

Pin the interpreter (recommended on Windows):

# CLI
set FRIDA_MCP_PYTHON=C:\Users\You\AppData\Local\Programs\Python\Python312\python.exe
"%FRIDA_MCP_PYTHON%" -m pip install pymobiledevice3

Cursor / Claude MCP config example:

{
  "mcpServers": {
    "frida-ios": {
      "command": "node",
      "args": ["D:/Project/tk/frida-mcp/dist/index.js"],
      "env": {
        "FRIDA_MCP_PYTHON": "C:\\Users\\You\\AppData\\Local\\Programs\\Python\\Python312\\python.exe"
      }
    }
  }
}

# image or small mp4 (prefer no other session_open during video import)
pnpm cli call photos_import_file --localPath D:\path\to\clip.mp4 --mediaType video
pnpm cli call photos_list --mediaType video
pnpm cli call photos_clear

Video tip: concurrent App sessions (e.g. Preferences open via session_open) can delay sqlite verify → needsRetry:true with a valid localIdentifier. Close other sessions and photos_list / re-import; do not treat needsRetry as silent success.

AFC helper: scripts/afc_tool.py (preflight / push / list-untrashed / rm-dcim). Host = Photos.app only. SQLite query aligns with fleetcontrol (ZKIND in (0,1,2) + extensions).

session_open { bundleId: TikTok, withSpringBoard: true }
dual_ping                    # both channels pong at once
# later, can issue app + sb work concurrently if client allows

Install & build

cd D:\Project\tk\frida-mcp
pnpm install
pnpm build

Product surface

MCP vs CLI sessions (read this)

1. Embedded MCP = its own Node process + own sessionStore (Cursor/Grok default).

2. CLI = another process; cannot see the MCP session.

3. To share one Frida session: run the daemon, then set FRIDA_MCP_MODE=daemon on both MCP and CLI.

4. Without daemon, open/close in CLI is independent of Cursor.

5. App acts are serialized in-process (AI parallel tap+swipe will queue, not race).

# CLI (after build) — separate process unless daemon
pnpm cli help
pnpm cli open --bundleId com.ss.iphone.ugc.Ame --withSpringBoard
pnpm cli call wait --ms 4000
pnpm cli snap --limit 20
pnpm cli call net_dump --summaryOnly
pnpm cli close

Open-source safety (net_dump defaults):

• Redact Authorization / Cookie / *Token*

• Drop data: URLs (base64 images)

• Fold binary / octet-stream body previews

• summaryOnly: true for host counts only

• redact:false / includeDataUrls / includeBinaryBodies only on trusted local machines — never paste raw dumps into issues/PRs.

Typing (real input path): Feed → tiktok_open_search (preferred; retries magnifier points) → smart_type_text on the wide [input] search bar → then tap the narrow 搜尋 / 搜索 / Search submit button to run the query.
Never smart_type_text on nav tabs or on the submit 搜尋 button itself.
Nav / composer chips (e.g. “What's on your mind”) are not fields → NOT_INPUT.

SB test alert: sb_alert_trigger → sb_alert_list (hasAlert) → single sb_alert_dismiss (post-settle cleared) or stacked sb_alert_dismiss({ all: true }); if needsRetry re-list / retry all.

Debug tools (rpc_call, dump_modal, set_text_at_point): registered by default in FRIDA_MCP_TOOLS=all (prefixed [debug]). Hide with FRIDA_MCP_ALLOW_DEBUG_TOOLS=0, or hide advanced+debug with FRIDA_MCP_TOOLS=core.

Modes

Embedded (default, recommended for Grok/Cursor trial)

Session lives inside the MCP process. No daemon, no env:

node dist/index.js
# or
pnpm dev

Daemon + thin MCP (NSSM) — shared session with CLI

1. Daemon holds Frida session on 127.0.0.1:18765

2. stdio MCP and CLI forward when FRIDA_MCP_MODE=daemon (or FRIDA_MCP_DAEMON=1)

pnpm start:daemon
# other terminal / Cursor:
set FRIDA_MCP_MODE=daemon
node dist/index.js

Grok config (~/.grok/config.toml)

Why no args? MCP spawns command + optional args. We ship bin/frida-mcp.cmd which already runs node dist/index.js, so config only needs the launcher path:

[mcp_servers.frida-ios]
command = "D:/Project/tk/frida-mcp/bin/frida-mcp.cmd"
enabled = true

Optional daemon mode (daemon must be running separately):

[mcp_servers.frida-ios]
command = "D:/Project/tk/frida-mcp/bin/frida-mcp.cmd"
enabled = true

[mcp_servers.frida-ios.env]
FRIDA_MCP_MODE = "daemon"

Cursor mcp.json

{
  "mcpServers": {
    "frida-ios": {
      "command": "D:/Project/tk/frida-mcp/bin/frida-mcp.cmd"
    }
  }
}

TikTok red lines

• Never dump_tree / find_view / find_buttons / dump_login_gate (MCP gates these).

• Read UI only via screen_snapshot → collectTextsWithFrames.

• Prefer session_open mode=spawn for reliable touch.

• After open, wait 3000–5000 ms before first snapshot.

• Refs only valid for last snapshot — re-snapshot after UI changes.

Tools

Refs expire after tap/swipe and across snapshot generations. Off-screen / zero-size nodes are marked and rejected on tap.

Humanized typing (inputText)

Agent: agent/text_input/comment.js (same approach as fleetcontrol).

• Default perCharDelayMs=90; agent adds randomDelay(base, jitter≈base) (jitter ≥ 30ms).

• Insert fallbacks: insertText → replaceRange → inner insertText → setText + notify.

• Nav tabs / chips like “Home” or “What's on your mind” are not inputs → NOT_INPUT (session stays alive).

• Prefer smart_type_text on a real field ref; use first_responder if unsure (canInsertText).

• screen_snapshot defaults: onScreenOnly=true, limit=40; optional search / showDiff.

• tap / swipe / smart_type_text default resnapshot=true (returns snapshot).

• Errors return { code, recovery[] } (e.g. SCRIPT_DESTROYED → respawn).

• Start probes with probe_help; prefer first-class tools over [debug] rpc_call (hide debug with FRIDA_MCP_ALLOW_DEBUG_TOOLS=0).

Network capture (reverse-engineering)

# Best: capture launch traffic (hooks before resume)
session_open {
  bundleId,
  captureNet: true,
  netOptions: { captureMode: "all", maxBody: 16384, captureResponse: true, signTrace: true }
}
  → use app (Inbox / Profile)
  → net_dump({ redact:false, dedupe:false, query:"imapi|inbox|/im/|profile/self|security-argus", includeBinaryBodies:true, limit:100 })
  → tiktok_sign({ action: "last" })   # recent sign headers (+ backtrace if signTrace)

• captureMode: nsurl | ttnet | all (default).

• Signing model (general capability): MCP does not reimplement offline X-Gorgon / X-Argus. Instead it uses in-process TTNet (TTNetworkManager JSON request) so the App's MetaSec signs, and net_* / tiktok_sign capture x-security-argus / x-Tt-Token / x-metasec-* I/O (+ optional signTrace backtrace).

• iOS sign headers (45.x): x-security-argus, x-Tt-Token, x-metasec-*, ticket/device-guard — classic X-Gorgon / X-Argus names are often absent on this build.

• Responses: captureResponse:true uses TTNet onReadResponseData + setIsCompleted. Do not hook onURLFetchComplete (kills script). Many JSON/IM payloads may still arrive empty via this path (protobuf/other channels); binary/CDN bodies usually populate. Prefer ttnetRequest callback JSON for posts/list APIs.

• DM / works URLs seen on device: imapi-*.tiktokv.com/v1/message/get_by_user, …/v2/message/get_by_user_init, tiktok/v1/im/inbox_data/get, aweme/v1/user/profile/self, feed/post endpoints.

• IM inbox/reply:

  • tiktok_inbox — refresh Inbox + Message Requests and return username, real text content, conversationId, peerUid.

  • tiktok_reply / tiktok_im send_text — default dryRun:true. With dryRun:false, opens the real chat composer (ChatInputTextView + 傳送), and returns sent:true only after the exact text is re-read from live AWEIMTextMessage models (blank bubbles / network-callback-only success are rejected). transport:"sdk" is disabled.

  • tiktok_im action: messages — list recent messages with real text when available; open_chat accepts conversationId or peerUid.

• Posts (tiktok_posts): self post list via TTNet to aweme/v1/aweme/post/ (override url/userId if needed).

• Add Phone popup attribution (no dedicated tool):

  1. session_open with captureNet + reproduce the popup

  2. net_dump({ query: "passport/account|bind_phone|mobile", redact:false, dedupe:false }) — avoid bare phone (matches iPhone device_type noise)

  3. tiktok_im({ action: "phone_status" }) — on this build: AWEUserService.sharedService → currentLoginUser:

     • havePhoneNumber / isPhoneBinded false + empty bindPhone ⇒ account unbound (not just a cosmetic prompt)

     • canShowThirdPartyPhoneBindingPopup / is3pBindPopupRequestShow distinguish third-party bind UI vs mandatory add-phone

  4. Boot traffic often includes passport/account/info/v2 and passport/token/beat/v2

• RE dump tip: redact:false, dedupe:false, includeBinaryBodies:true.

Advanced TikTok tools (not core)

NSSM (only after device tools work)

# Admin
cd D:\Project\tk\frida-mcp
pnpm build
.\scripts\install-nssm-service.ps1
nssm start FridaMcpDaemon

Uninstall: .\scripts\uninstall-nssm-service.ps1

Logs: logs/daemon.stdout.log, logs/daemon.stderr.log

Typical probe

1. device_list

2. app_list → find TikTok bundle

3. session_open { "bundleId": "…", "mode": "spawn" }

4. wait { "ms": 4000 }

5. ping → pong

6. screen_snapshot → refs

7. tap { "ref": "t3" } → screen_snapshot again

Agent

• Source: agent/agent_main.js (+ imports), includes ping

• Override: FRIDA_AGENT_ENTRY=path/to/agent_main.js

• Compile: Frida Compiler, projectRoot = repo root (frida-objc-bridge in node_modules)

License

Private / internal use.