Frida Mobile MCP

frida-mobile-mcp

Frida 17 を通じて Android および iOS アプリの動的計測を AI エージェントに提供する MCP サーバーです。REA、ReVa（Ghidra）、IDA の MCP サーバーと連携して動作します。71 個のツールを提供します。デバイス、セッション、スクリプトを管理する高レベルのツール（アプリの調査、Java／ObjC／ネイティブメソッドのフック、呼び出しのトレース、到達可能性カバレッジのマッピングと、それに向けた UI の自律的な操作、メモリ内のシークレットの検出と再利用可能な friTap パターンへの変換、暗号処理の広範な調査、SSL ピンニングのバイパス、friTap による TLS キーと平文のキャプチャ、ビルド済み分析スクリプトの実行、カスタムスクリプトの検証）と、低レベルのプリミティブ（spawn／attach、モジュールとシンボルの列挙、アドレス解決、制御フロー分析、メモリダンプ）を備えています。アドレスには 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)
frida-mobile-mcp gadget --platform android --print   # generate a frida-gadget config.json + APK/IPA repackaging guidance

gadget コマンドは frida-gadget の config.json（--interaction listen または --interaction script）を生成し、APK／IPA の再パッケージ手順を出力します。ガジェットの埋め込みは、attach 時にスクリプトを読み込めるようになる前に .init_array／JNI_OnLoad で実行されるネイティブ検出を計測する唯一の方法であり、フィンガープリントとなる frida-server の :27042 ポートも取り除けます。詳しくは 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" }
    }
  }
}

クライアントごとの設定、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（それ以外の場合、固定されたエージェントは初回使用時にダウンロードされます）。また、初回の mobile_action で npx -y @mobilenext/mobile-mcp@latest を実行するためのネットワークアクセスが必要です。

Frida 17 の新機能

• ブリッジが同梱されます。 Frida 17 では、GumJS ランタイムに Java／ObjC ブリッジが同梱されなくなりました。npm run build:bridges は frida-java-bridge と frida-objc-bridge を dist/bridges/{java,objc}.js にバンドルします。サーバーは、プラットフォームに応じたブリッジ（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 は lint で検出されます。 validate_script は、Frida 17 で例外を発生させる静的な Module.findExportByName／findBaseAddress／enumerateExports、Memory.readX／writeX、および *Sync 列挙子を検出し、Module インスタンス／NativePointer での代替方法を提案します。生成されたスクリプトには、エージェントのプリアンブルから findExport(lib, name) と hookNative(lib, name, callbacks) ヘルパーが提供され、テンプレートのオプションは __FRIDA_MCP__.options として利用できます。
• analyze_native_function は Process.findFunctionRange と Frida 17.12 以降の ControlFlowGraph を使用します（線形逆アセンブルへのフォールバックが発生した場合は limitations で報告されます）。

ツールリファレンス

Tier 1：高レベルツール

ツール	説明
get_status	接続中のデバイス、アクティブなセッション（プラットフォーム、スクリプト数、最終アクティビティ）、フック、トレース、最近の切断／クラッシュを確認します。最初に実行し、セッションが失われた後にも実行してください。
frida_help	トピック別のヘルプです。トピック：overview、hooking、tracing、memory、scripts、native、tls、mobile、examples、advanced、evasion、script_catalog、script_api、recipes、interop。
detect_app_technologies	ライブラリ、フレームワーク、セキュリティ機構をフィンガープリントし、推奨するスクリプトの対象を返します。
explore_app	アプリを一時停止状態で起動し、インストゥルメントしてから再開します。pid、プラットフォーム、モジュール、フィルター済みクラス一覧を返します。
get_app_info	インストール済みのアーティファクトを特定します。バージョン、SDK レベル、デバッグ可能かどうか、インストーラー、およびデバイス上の sha256／サイズを含むすべての APK（base + splits）を返します。pull_to は APK を取得し、ハッシュを検証して、REA inspect_android_package などの静的解析ツールで使えるようにします。iOS では Frida アプリのパラメーターのみを返します。
search_classes_and_methods	実行中のアプリ内のクラスを正規表現で検索します（include_methods を指定するとメソッドも検索します）。
describe_class	読み込まれたクラス１つの完全な構造を返します。パラメーター／戻り値の型とフックに使える signature を含むすべてのメソッドオーバーロード、コンストラクター、フィールド、スーパークラス／インターフェイスを確認できます（ObjC では型エンコーディング付きセレクター）。署名を hook_method の evidence: {class, signature} に渡してください。
discover_crypto	javax.crypto を前提とせずに、アプリが暗号処理（または任意の API ファミリー）を行う箇所を特定します。Java／ObjC クラスとネイティブシンボル全体から、候補となるフック対象をランク付けして返します。
find_secrets_in_memory	メモリーを内容に基づいてスキャンし、秘密情報の構造を特定します。RC4 S-box（byte[] または Java int[256]）、AES キースケジュール（aeskeyfind — 暗号化と復号化の両方、モード非依存）、ChaCha20／Salsa20 キー（sigma 定数）、高エントロピーの 16／24／32 バイトキー、PEM／DER 秘密鍵、JWT が対象です。それを使用するコードに到達しなくてもキーを見つけられます。
generate_memory_pattern	発見した秘密情報を再利用可能なアンカーパターン（キー付近の安定したバイトシグネチャとオフセット）に変換します。scan_memory で再検出するか、friTap の capture_tls に渡します（patterns／offsets）。
monitor_crypto	暗号オラクルを広く探索します。可能性の高い暗号処理のシンク（アプリ独自のクラス + javax.crypto／Mac／MessageDigest、iOS CommonCrypto、ネイティブ OpenSSL／BoringSSL）をすべて一度に特定してフックし、すべてのキー、入力、出力を 16 進数でダンプします。
trace_coverage	到達可能性マップです。クラス／パッケージ／モジュールのスコープに低コストの永続的なエントリーフックを設定し、trigger_and_wait による操作を通じてカバー済みと未実行の対象を追跡します。これにより、まだ実行していないコードが分かります。
drive_coverage	インストゥルメント済みセッションの UI を自動操作し、未カバーのコードを目指します。画面上の要素を幅優先でタップし、暗号／秘密情報のシグナルが検出された瞬間（またはカバレッジが停滞した場合／max_steps に達した場合）に停止します。monitor_crypto／trace_coverage と組み合わせてください。
watch_loads	後から読み込まれる .so ライブラリと Java クラス、および Frida 対策プローブを監視し、アプリの実行中に watch_event メッセージを出力します。
trigger_and_wait	UI 操作を実行し、その結果のフック／メッセージ出力が届くまで待機します。これにより、タップでどのフックが実行されたか（または何も実行されなかったか）が分かります。
hook_method	Java（com.example.Class.method）、ObjC（-[Class sel:]）、またはネイティブの対象（libssl.so!SSL_read、libfoo.so+0x1234、0x7f...、!open）を、自動セッション管理でフックします。バックトレースは module+0xoff (symbol) 形式です。
trace_method	指定した期間、グロブパターン（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	以下の 9 個のビルド済みスクリプトのいずれかを実行します。script_name を指定せずに呼び出すと一覧を表示します。
bypass_ssl_pinning	ワンクリックでピンニングを回避します（Android：TrustManager、OkHttp CertificatePinner、Conscrypt。iOS：SecTrust、ATS、BoringSSL）。
capture_tls	friTap を使い、TLS セッションキー（NSS キーログ）と、オプションで復号済み平文／合成 pcap を取得します。OpenSSL／BoringSSL、Conscrypt、NSS、GnuTLS、wolfSSL、mbedTLS、Secure Transport などに対応しています。ストリップ済みライブラリ用に friTap の patterns／offsets（例：generate_memory_pattern または BoringSecretHunter から取得）を指定できます。
read_memory	任意のアドレス表記から最大 4 MB を読み取り、16 進数データと絶対アドレス、module+offset を返します。
write_memory	16 進数のバイト列をメモリーに書き込みます。memoryWriteEnabled が有効でない限り無効です。
scan_memory	バイトパターン（48 89 5c 24 ?? 57）をスキャンします。オプションでモジュールに範囲を限定できます。
get_messages	バッファーされたフック呼び出し、トレースヒット、send() の出力、エラーを取得します。since でページネーションします。
get_evidence	evidence_id を指定して、永続化されたツールの結果（パラメーター、ステータス、構造化された結果）を再読み込みします。
export_evidence_bundle	永続化された結果を JSON または Markdown のバンドルとして、インラインまたはファイルにエクスポートします。
stop_instrumentation	対象のすべてのフック、スクリプト、トレースを削除し、デタッチします。
unload_script	セッションへのアタッチを維持したまま、単一のスクリプト（フック、トレース、カスタムスクリプト）をアンロードします。
mobile_action	モバイル向け MCP UI 自動化（スクリーンショット、要素、タップ、スワイプ、入力、アプリ起動、アプリ一覧）へのゲートウェイです。
search_recipes	すぐに実行できるクラシック JS レシピの目的別ライブラリを検索します（カスタムの暗号キー取得、ネイティブ／JNI フック、クラスローダー／インテント／WebView、iOS Keychain）。execute_script で調整・実行できるソース付きのレシピを、ランク付けして返します。
save_script	再利用できるよう、~/.config/frida-mobile-mcp/scripts にスクリプトを保存します。allowCustomScripts が必要です。
list_saved_scripts	save_script で保存したスクリプトを一覧表示します。
run_saved_script	保存済みスクリプトを名前で指定し、対象に対して実行します。allowCustomScripts が必要です。
export_script	スクリプトを、通常の frida -U -f <pkg> -l file.js CLI で実行できる単独のクラシック .js としてエクスポートします（プリアンブル + ソース。ブリッジは frida-tools CLI によって提供され、バンドルには含まれません）。

Tier 2: advanced primitives

ツール	説明
list_devices	ローカル、USB、リモートの Frida デバイス（frida-ls-devices）。
select_device	ID、種類、またはリモートホストでアクティブなデバイスを選択します。
get_device_info	OS バージョン、アーキテクチャ、システムパラメーターを取得します。
list_processes	実行中のプロセス（frida-ps）。
list_applications	インストール済みおよび実行中のアプリケーション。
get_frontmost_application	フォアグラウンドのアプリケーション。
spawn_process	早期のインスツルメンテーションのためにプロセスを一時停止状態で起動します。resume_process で再開します。
attach_process	PID または名前で実行中のプロセスにアタッチします。
resume_process	一時停止中のプロセスを再開します。
kill_process	プロセスを終了します。
detach_session	セッションをデタッチし、そのスクリプトをアンロードします。
list_sessions	このサーバーが管理するセッション。
spawn_gating	デバイス全体の spawn gating を有効化／無効化／一覧表示します。新たに起動したプロセス（子プロセスや分離プロセスを含む）を一時停止状態に保ち、早期のインスツルメンテーションを可能にします。resume_process で解放します。
child_gating	セッションで child gating を有効化／無効化し、フォークまたは exec された子プロセスをインスツルメンテーションのために一時停止状態に保ちます。
eternalize_script	読み込み済みのスクリプトをターゲットに固定し、デタッチ後も存続させます（fire-and-forget：以降のメッセージ送信やアンロードはありません）。セッションを解放しながら、バイパス／モニターを実行したままにできます。
enumerate_modules	名前、ベース、終了アドレス、サイズ、パスを含む読み込み済みモジュール。正規表現の filter を指定できます。
enumerate_exports	モジュールのエクスポートをページ分割して取得します。
enumerate_imports	提供元のモジュールを含むモジュールのインポートをページ分割して取得します。
enumerate_symbols	エクスポートされていないシンボルやデバッグシンボルを含むシンボル。正規表現によるフィルターとエージェント内でのページ分割に対応しています（Linux、Android、iOS、macOS）。
resolve_address	0x7f... を module+0xoffset（および最も近いシンボル）に変換し、module+0xoff／module!sym を絶対アドレスに変換します。
analyze_native_function	関数の範囲、基本ブロックとエッジ、先頭の命令を取得します。アドレスは絶対アドレスおよび module+0xoffset で表示されます。
dump_module_memory	モジュールのベース相対メモリーをホスト上のファイル（cwd、temp ディレクトリ、または ~/.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 でフックを削除します。
frida_server_status	Android（adb）：frida-server の PID、デバイスの CPU ABI、対応する Frida リリースのアーキテクチャ、インストール済みの frida-node バージョンに対応する GitHub の .xz アセット URL を報告します。
frida_server_install	Android（adb）：ローカルの（展開済み）frida-server バイナリをデバイスに転送し、chmod 755 を実行します。
frida_server_start	Android（adb）：カスタムのリッスンアドレス／ポートとバイナリ名を指定し、frida-server をデーモンとして起動します（必要に応じて su 経由）。デフォルト以外のポート／名前を使うと、:27042／frida-server のスキャンを回避できます。allowedDevices を適用します。
frida_server_stop	Android（adb）：一致する frida-server プロセスに停止シグナルを送ります（pkill、必要に応じて su 経由）。
adb_shell	Android（adb）：任意のデバイスシェルコマンドを実行します。デフォルトでは無効です。allowAdbShell（設定）または FRIDA_MCP_ALLOW_ADB_SHELL=1 が必要です。
adb_logcat	Android（adb）：直近の N 行の logcat をダンプします（1 回のみ実行）。オプションで tag:priority フィルターを指定するか、バッファーをクリアできます。
adb_pull / adb_push	Android（adb）：ホストとデバイス間でファイルを転送します。
adb_forward	Android（adb）：ポートフォワードを追加／削除／一覧表示します（デフォルト以外のデバイスポートで動作する frida-server に接続できます）。
inject_library	Frida のインジェクターを使用して、ホスト上のネイティブライブラリー（.so／.dylib）を JS エンジンとは独立してプロセスに注入します。ビルド済みの gadget／エージェントやカスタム .so を使う場合の同等機能です。デフォルトでは無効です。allowNativeInjection（設定）または FRIDA_MCP_ALLOW_NATIVE_INJECTION=1（allowCustomScripts とは別の機能）と、アーキテクチャに適合するライブラリーが必要です。

mobile_action ゲートウェイ

mobile_action({ action, params }) は、遅延起動される mobile-mcp プロセス（デフォルトは npx -y @mobilenext/mobile-mcp@latest。mobileMcp で設定可能、--no-mobile-mcp で無効化）に処理を転送します。利用可能なアクションを一覧表示するには、action を指定せずに呼び出してください。すべての Frida ツールはこれなしでも動作します。起動できない場合、エラーは MOBILE_MCP_UNAVAILABLE です。

サーバーは frida:// リソース（バージョン、デバイス、プロセス、アプリ、セッション、メッセージ、スクリプトカタログ、frida://evidence と frida://evidence/{id} を介した永続化済みの証拠）と、5 つのワークフロープロンプト（explore_app、security_audit、trace_functionality、write_frida_script、hunt_secrets）も公開します。

事前構築済みスクリプト

スクリプト	目的
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 を監視します
anti_frida_evasion	Frida の検出に RASP が使用するネイティブプリミティブを監視（デフォルトの mode=report）または無効化（mode=spoof。memoryWriteEnabled が必要）します：/proc/self/{maps,status,task} の読み取り、strstr による「frida」の検索、スレッド名／dlopen のプローブ、iOS dyld イメージのスキャン

アドレス表記と証拠エンベロープ

ネイティブアドレスを受け取る、または返すすべてのツールで、同じ表記を使用します。

形式	意味	例
module!symbol	エクスポートまたは ELF／Mach-O シンボル	libssl.so!SSL_write
module+0xOFFSET	モジュールベースからのオフセット（Ghidra／IDA の RVA）。10 進数の 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 が含まれます。エラーを含むすべての結果は証拠ストアにも保存され、get_evidence、export_evidence_bundle、frida://evidence/{id} リソースから evidence_id を使って取得できます（frida://evidence は最新の 100 件を一覧表示します）。フィールドの意味とエラーコードの表は docs/interop.md に、関連するエージェントのワークフローは skills/mobile-dynamic-analysis/SKILL.md に記載されています。

REA、ReVa、IDA との連携

frida-mobile-mcp は、ReVa（Ghidra）、ida-pro-mcp（IDA Pro）、REA と並行して動作するように設計されています。静的解析側はコードが何を示しているかを明らかにし、このサーバーは実行時に何が起きるかを明らかにします。静的解析ツールで libfoo.so+0x1234 が見つかった場合、hook_method または analyze_native_function にその文字列をそのまま渡せます。バックトレースと resolve_address は、逆コンパイルに使える同じ形式でオフセットを返します。enumerate_modules は Ghidra／IDA プロジェクトのリベースに必要な base／end を返し、dump_module_memory はアンパック済みライブラリのベース相対イメージを raw import 用に書き出し、capture_tls は静的解析で見つかったラッパーが実際にワイヤー上に送信するバイト列を表示します。3 つのサーバーを含むクライアント設定と、静的解析 → 動的解析 → 静的解析の完全な手順については、docs/interop.md を参照してください。

REA は、Android の静的解析（inspect_android_package、inspect_android_method）、ADB の管理、デスクトップバイナリ向けの汎用 Frida レーンを担当します。このサーバーは、モバイルの実行時解析（Java／ObjC ブリッジ、ビルド済みスクリプト、TLS キー、メモリ、UI 操作）を担当します。両方を同じクライアントに登録し、get_app_info から始めて、両サーバーが同じ APK ハッシュを解析するようにしてください。FRIDA_MCP_TOOL_PROFILE=coreとFRIDA_MCP_TOOLS_EXCLUDE=adb_,frida_server_を設定すると、統合カタログを小さく保てます。両サーバーは引用可能なevidence_id を含むエビデンスエンベロープと、export_evidence_bundle` ツールを返すため、1 つの調査結果台帳で両方を引用できます。ルーティングルール、インストールコマンド、フィールドとエラーコードの対応付け、APK → 静的解析 → フック → レポートの手順については、docs/rea.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 エンドポイントは、クライアントごとに 1 つの MCP セッションを使用します（Mcp-Session-Id）。このヘッダーを付けた DELETE /mcp を送信すると、セッションが終了します。サーバーはデフォルトでループバックにバインドされます。--host がループバックアドレスでない場合は Bearer トークン（--http-token または FRIDA_MCP_HTTP_TOKEN）が必須で、トークンがない状態ではサーバーは起動しません。Host ヘッダーと Origin ヘッダーは、バインドされたホストに対して検証されます（DNS リバインディング対策）。TLS は使用しません。ネットワークをまたいで接続する場合は、リバースプロキシまたは SSH トンネルを使用してください。--port 0 を指定すると、空きポートが選択されます。バインドされた URL は stderr に JSON 行として出力されます。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,
  "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 }
}

変数	デフォルト	説明
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_ALLOW_NATIVE_INJECTION	未設定	1／true にすると inject_library（ネイティブの .so／.dylib インジェクション）が有効になります。カスタムスクリプトとは別の機能です
FRIDA_MCP_ALLOW_ADB_SHELL	未設定	1／true にすると adb_shell（任意のデバイスシェルコマンド）が有効になります
FRIDA_MCP_DEBUG	未設定	1 にすると、stderr へのデバッグログ出力が有効になります。--debug と同じです
FRIDA_MCP_REMOTE	未設定	起動時にリモートデバイスとして追加する frida-server の host[:port]（ポート 27042）です。--remote と同じです
FRIDA_MCP_REMOTE_TOKEN	未設定	その frida-server の認証トークン（frida-server --token）です。--remote-token と同じです
FRIDA_MCP_REMOTE_CERT	未設定	TLS frida-server の PEM 証明書のパス（frida-server --certificate）です。--remote-cert と同じです
FRIDA_MCP_HTTP_TOKEN	未設定	HTTP トランスポート用のベアラートークンです。--http-token と同じです
FRIDA_MCP_SCHEMA_PROFILE	full	compact にすると、コンテキストウィンドウが小さい場合にツールスキーマを短縮します
FRIDA_MCP_TOOL_PROFILE	full	core にすると、コアツールセットのみを登録します（tools/list が小さくなります。たとえば REA と併用する場合）。--tool-profile も使用できます。FRIDA_MCP_SCHEMA_PROFILE=compact と組み合わせると、カタログは full の 17% になります。docs/rea.md を参照してください
FRIDA_MCP_TOOLS_EXCLUDE	（なし）	登録しないツール名のグロブをコンマ区切りで指定します。たとえば、REA の ADB ツールでデバイスを操作する場合は adb_*,frida_server_* と指定します。--exclude-tools も使用できます。get_status は件数を hidden_tools として報告します
FRIDA_MCP_MAX_RESPONSE_CHARS	25000	1 回のツール応答の切り詰め上限です
FRIDA_MCP_RUNTIME	Frida のデフォルト	インジェクトするエージェントのスクリプトランタイムとして qjs または v8 を指定します
FRIDA_MCP_SNAPSHOTS	未設定	1 にすると、セッションごとに bridge バンドルの V8 スナップショットを事前にウォームアップします（FRIDA_MCP_RUNTIME=v8 の場合のみ）。docs/clients.md を参照してください
FRIDA_MCP_EVIDENCE	1	0 にすると、ツールの結果がエビデンスストアに保存されなくなります。設定項目 evidence.enabled と同じです
FRIDA_MCP_EVIDENCE_PATH	~/.config/frida-mobile-mcp/evidence	エビデンスストアのディレクトリです（YYYY-MM-DD/<evidence_id>.json と index.jsonl を保存し、モードは 0600）
FRIDA_MCP_EVIDENCE_MAX_MB	200	エビデンスストアのサイズ上限です。上限を超えると最も古いレコードが削除されます
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	ローカルにエージェントが見つからない場合にダウンロードする friTap のタグです
FRITAP_AGENT_SHA256	v2.5.2 用に固定	選択した FRITAP_VERSION タグの friTap エージェントをダウンロードした際の、プレフィックスのない sha256 値です。不一致の場合、バンドルは拒否されます

セキュリティガードレール

• execute_script とカスタムの hook_function ハンドラー本体は、allowCustomScripts が有効でない限り CUSTOM_SCRIPTS_DISABLED で拒否されます。組み込みスクリプトと型付きフックツールには、この設定は不要です。
• write_memory は、memoryWriteEnabled が有効でない限り MEMORY_WRITE_DISABLED で拒否されます。ターゲットメモリに書き込む組み込みスクリプト（例：mode=spoof を指定した anti_frida_evasion）と、spoof=true を指定した watch_loads にも同じ制限が適用されます。
• inject_library は、allowNativeInjection が有効でない限り NATIVE_INJECTION_DISABLED で拒否されます。この機能は allowCustomScripts とは別に管理されるため、JS エージェントを許可しながらネイティブコードのインジェクションを禁止できます。
• allowedDevices は使用できるデバイス ID を制限します（空の場合はすべて許可）。
• スクリプトのロード、メモリの読み取り／スキャン、アタッチ／スポーンには、1 分あたりのレート制限があります（RATE_LIMIT_EXCEEDED。再試行可能）。maxSessions と sessionTimeoutMinutes は、同時セッション数とアイドル状態のセッションを制限します。
• すべてのツール呼び出しは、その evidence_id とともに auditLogPath の JSONL 監査ログに追記されます。
• すべてのツール結果（メモリダンプのメタデータ、メモリの読み取り結果、検出されたシークレットを含む）は、証跡パス（evidence.path。既定値は ~/.config/frida-mobile-mcp/evidence）にモード 0600 で保存されます。無効にするには FRIDA_MCP_EVIDENCE=0 を設定します。
• dump_module_memory は、現在のディレクトリ、OS の一時ディレクトリ、または ~/.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」／スポーン後にアプリが終了する：スポーンしたアプリが 10 秒以上サスペンド状態のままだと、Android によって終了されます（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 を含むディレクトリを指定してください。
• npm install で frida の事前ビルド済みパッケージのダウンロードに失敗する：frida パッケージはインストールスクリプトでネイティブバインディングを取得します。インストールスクリプトが許可されていることを確認してください（npm ci --foreground-scripts でダウンロード状況を確認できます）。また、GitHub のリリースにアクセスできることを確認してください。
• デバイスが 2 台アタッチされている：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_MCP_E2E_DEVICE=emulator-5556 npx vitest run test/fritap/capture-tls.e2e.test.ts

従来の FRIDA_E2E=1、FRIDA_DEVICE_ID、FRIDA_E2E_TARGET という名前も、capture_tls テストでは引き続き使用できます。

コミットには Conventional Commits（feat:、fix:、docs: など）を使用します。release-please がリリース PR を作成し、CHANGELOG.md を管理します。また、release.yml の publish ジョブが OIDC トラステッドパブリッシングを介して npm に公開します。CONTRIBUTING.md と AGENTS.md を参照してください。

ライセンス

MIT