Ios Files

ios-files-mcp

iOS デバイスのファイルシステムへの SSH/SFTP アクセスを制御する MCP stdio サーバーです。

AI MCP client -> ios-files-mcp on your computer -> SSH/SFTP -> iOS device

クイックインストール

必要なもの：

• Node.js 20+
• iOS デバイスで OpenSSH が実行されていること
• お使いのコンピューターからデバイスに SSH 接続できること

Settings -> Wi-Fi -> your network -> IP Address で iOS デバイスの IP アドレスを確認し、次のコマンドでテストしてください。

ssh [email protected]

コーディングエージェント用のコマンドを実行してください。192.168.1.23 と change-me を置き換えてください。変更していない場合、デフォルトの SSH パスワードは alpine です。

Codex

npx -p github:xtofuub/ios-files-mcp iosfiles-mcp --client codex --host 192.168.1.23 --password change-me

~/.codex/config.toml に書き込みます。

Claude Desktop

npx -p github:xtofuub/ios-files-mcp iosfiles-mcp --client claude --host 192.168.1.23 --password change-me

Claude Desktop の MCP 設定に書き込みます。

OpenCode

npx -p github:xtofuub/ios-files-mcp iosfiles-mcp --client opencode --host 192.168.1.23 --password change-me

~/.config/opencode/opencode.json に書き込みます。

VS Code

MCP サーバーを有効にするワークスペースフォルダーで、このコマンドを実行してください。

npx -p github:xtofuub/ios-files-mcp iosfiles-mcp --client vscode --host 192.168.1.23 --password change-me

.vscode/mcp.json に書き込みます。

サポートされているすべてのクライアント

npx -p github:xtofuub/ios-files-mcp iosfiles-mcp --client all --host 192.168.1.23 --password change-me

サポートされている --client の値：

codex      -> ~/.codex/config.toml
claude     -> Claude Desktop config
opencode   -> ~/.config/opencode/opencode.json
vscode     -> .vscode/mcp.json in the current folder
all        -> all supported clients

インストーラーは ios-files MCP サーバーのエントリーを書き込み、既存の設定ファイルを .bak にバックアップします。

Hermes バイトコードデコーダーをオプションでインストールする場合：

npx -p github:xtofuub/ios-files-mcp iosfiles-mcp --client codex --host 192.168.1.23 --password change-me --install-hermes

Hermes デコーダーが必要なのは、React Native Hermes バイトコードバンドルをデコードする場合のみです。このフラグを指定すると、利用可能な場合は Python/pipx を使用して hermes-dec をインストールします。

radare2 による静的解析については、以下の radare2 の静的解析ツールのセクションを参照してください。推奨される方法は、Sileo 経由で iOS デバイス自体に radare2 をインストールすることです。

USB SSH

iproxy で iOS デバイスの SSH をローカルポートに転送してから、localhost を使ってインストールします。

ssh -p 2222 [email protected]
npx -p github:xtofuub/ios-files-mcp iosfiles-mcp --client codex --host 127.0.0.1 --port 2222 --password change-me

USB SSH でも通常の SSH 認証を使用するため、パスワードまたは SSH キーを使用してください。

MCP の手動設定

インストーラーは次のコマンドを書き込みます。

{
  "command": "npx",
  "args": ["--yes", "--quiet", "github:xtofuub/ios-files-mcp"],
  "env": {
    "IOS_FILES_MCP_HOST": "192.168.1.23",
    "IOS_FILES_MCP_USERNAME": "mobile",
    "IOS_FILES_MCP_PASSWORD": "change-me"
  }
}

Claude/Cline 形式のクライアントでは mcpServers.ios-files の下に、VS Code では servers.ios-files の下に設定してください。

パッケージを明示的にインストールする場合：

npm install github:xtofuub/ios-files-mcp

npm install で MCP 設定も書き込むには、先にインストーラーの環境変数を設定してください。

$env:IOS_FILES_MCP_INSTALL_CLIENTS="codex"
$env:IOS_FILES_MCP_HOST="192.168.1.23"
$env:IOS_FILES_MCP_USERNAME="mobile"
$env:IOS_FILES_MCP_PASSWORD="change-me"
npm install github:xtofuub/ios-files-mcp

Hermes デコーダーも必要な場合は、この環境変数を追加してください。

$env:IOS_FILES_MCP_INSTALL_HERMES="true"

便利な環境変数：

IOS_FILES_MCP_HOST
IOS_FILES_MCP_PORT
IOS_FILES_MCP_USERNAME
IOS_FILES_MCP_PASSWORD
IOS_FILES_MCP_KEY_PATH
IOS_FILES_MCP_ALLOWED_ROOTS
IOS_FILES_MCP_READ_ONLY
IOS_FILES_MCP_ALLOW_WRITES
IOS_FILES_MCP_REQUIRE_WRITE_APPROVAL
IOS_FILES_MCP_ENABLE_R2
IOS_FILES_MCP_R2_MODE
IOS_FILES_MCP_R2_DEVICE_R2_PATH
IOS_FILES_MCP_R2_DEVICE_RABIN2_PATH
IOS_FILES_MCP_R2_PATH
IOS_FILES_MCP_RABIN2_PATH
IOS_FILES_MCP_R2_TIMEOUT_MS
IOS_FILES_MCP_R2_MAX_OUTPUT_BYTES
IOS_FILES_MCP_R2_MAX_BINARY_SIZE
IOS_FILES_MCP_SFTP_OP_TIMEOUT_MS
IOS_FILES_MCP_CONFIG

オプションの JSON 設定ファイル

ほとんどのユーザーには MCP の env の使用をおすすめします。JSON 設定ファイルが必要なのは、高度な設定やローカル環境での設定の場合のみです。

最小限の例：

{
  "host": "192.168.1.23",
  "port": 22,
  "username": "mobile",
  "password": "change-me",
  "readOnly": true,
  "allowWrites": false
}

すべてのオプションについては ios-files-mcp.config.example.json を参照してください。

IOS_FILES_MCP_CONFIG で MCP に設定ファイルを指定します。

{
  "servers": {
    "ios-files": {
      "command": "npx",
      "args": [
        "--yes",
        "--quiet",
        "github:xtofuub/ios-files-mcp"
      ],
      "env": {
        "IOS_FILES_MCP_CONFIG": "/path/to/ios-files-mcp/ios-files-mcp.config.json"
      }
    }
  }
}

または、引数として渡します。

{
  "mcpServers": {
    "ios-files": {
      "command": "npx",
      "args": [
        "--yes",
        "--quiet",
        "github:xtofuub/ios-files-mcp",
        "--config",
        "/path/to/ios-files-mcp/ios-files-mcp.config.json"
      ]
    }
  }
}

ローカルテスト

次のコマンドはヘルプを表示して終了します。

npx --yes --quiet github:xtofuub/ios-files-mcp --help

次のコマンドは MCP サーバーを起動し、MCP クライアントからの接続を待ちます。

$env:IOS_FILES_MCP_HOST="192.168.1.23"
$env:IOS_FILES_MCP_USERNAME="mobile"
$env:IOS_FILES_MCP_PASSWORD="change-me"
npx --yes --quiet github:xtofuub/ios-files-mcp

停止するには Ctrl+C を押してください。

開発

クローンしたリポジトリから：

npm install
npm run build
npm run typecheck
node dist/index.js --help

NPX を使わずにローカルで MCP をテストするには、MCP クライアントの接続先として絶対パスを指定した node dist/index.js を設定してください。

最初の MCP 呼び出し

アプリのディレクトリが空に見える場合は、ここから始めてください。

ios_connection_doctor()
ios_doctor()
ios_diagnose_roots()

ローカルの MCP クライアント設定を確認してください。

ios_mcp_config_status()
ios_config()

YouTube を探すには：

ios_find_app("YouTube")
ios_find_app("com.google.ios.youtube")
ios_snapshot_app("com.google.ios.youtube")
ios_app("com.google.ios.youtube")

アプリの plist を調べるには：

ios_read_plist("/private/var/containers/Bundle/Application/<UUID>/YouTube.app/Info.plist")

アプリのパス

アプリのデータコンテナ：

/var/mobile/Containers/Data/Application/<UUID>
/private/var/mobile/Containers/Data/Application/<UUID>

App Store の .app バンドル：

/var/containers/Bundle/Application/<UUID>/<AppName>.app
/private/var/containers/Bundle/Application/<UUID>/<AppName>.app

Info.plist は通常、データコンテナではなく .app バンドル内にあります。

安全性

サーバーはデフォルトで読み取り専用です。書き込みには、次の両方が必要です。

{
  "readOnly": false,
  "allowWrites": true
}

書き込みを有効にした場合も、デフォルトでは書き込みの承認が必要です。

{
  "requireWriteApproval": true,
  "writeApprovalTtlMs": 300000
}

書き込み可能なツールは、最初の呼び出しでは書き込みを行いません。approvalId を含む承認リクエストを返します。対象の操作を承認した場合は、同じツールを同じ引数と approvalId で再度呼び出してください。

承認 ID は次のとおりです。

one-use
time-limited
bound to the exact tool name and arguments

例：

ios_write_file("/var/mobile/test.txt", "hello")

承認リクエストが返されます。その後、承認された場合に限り：

ios_write_file("/var/mobile/test.txt", "hello", approvalId="the-id-from-the-request")

デフォルトでブロックされている操作：

/var/Keychains
/var/mobile/Library/Accounts
/var/mobile/Library/SMS
/var/mobile/Library/Mail
/private/var/db
/System
/usr
/bin
/sbin

すべての操作は ios-files-mcp.log に記録されます。ファイルの内容や秘密情報は記録されません。

ツール

基本的なファイルシステム

ツール	機能
ios_list_dir(path)	1 つのディレクトリ内のファイルとフォルダーを一覧表示します。
ios_stat(path)	種類、サイズ、所有者、モード、更新時刻などのファイルメタデータを返します。
ios_exists(path)	パスが存在しない場合もエラーにせず、パスの存在を確認します。
ios_hash_file(path)	ファイルの SHA-256 ハッシュを計算します。
ios_search_files(root, pattern, maxResults, maxDepth, includeMetadata, useCache)	上限付きで再帰的にファイル名／パスを検索します。インストール済みアプリを探す場合は、先にアプリ用ツールを使用してください。

ファイルの読み取り

ツール	機能
ios_read_file(path)	UTF-8 テキストファイルをチャットに読み込みます。読み取りサイズの上限は maxReadSize です。
ios_read_file_chunk(path, offset, length, encoding)	ファイルの範囲を指定して読み取ります。大きなテキストファイルやバイナリファイルに使用してください。
ios_tail_file(path, maxBytes)	ファイルの末尾のバイト列を読み取ります。ログに便利です。
ios_read_last_lines(path, lines, maxBytes)	テキストファイルの末尾から N 行を読み取ります。
ios_read_plist(path)	XML またはバイナリの plist ファイルを解析し、JSON で扱えるデータを返します。
ios_inspect_js_bundle(path)	React Native バンドルが通常の JavaScript、Hermes バイトコード、または不明なバイナリのいずれかを判定します。
ios_decode_js_bundle(path, mode, localPath, maxOutputBytes, beautify)	通常の .jsbundle ファイルを整形するか、バイトコードバンドルに対して設定済みの Hermes デコーダーを実行します。
ios_list_hermes_decoders()	設定済みのデコーダー、自動検出されたデコーダーコマンド、セットアップに関する注意事項を表示します。

コンピューターへのファイルのコピー

ツール	機能
ios_download_file(remotePath, localPath, overwrite)	iOS デバイスから、コンピューター上の許可されたローカルフォルダーに 1 つのファイルをコピーします。maxReadSize の制限は適用されません。
ios_zip_download(paths, localPath, overwrite)	iOS デバイス上の 1 つ以上のファイルやフォルダーを含む ZIP をローカルに作成します。アプリのフォルダー、ログ、またはまとめてエクスポートする場合に使用してください。

localPath は localArtifactRoots 内に指定する必要があります。

App Store アプリ用ヘルパー

ツール	機能
ios_find_app(query)	再帰検索に時間をかけず、表示名、.app 名、またはバンドル ID からインストール済みアプリを検索します。
ios_list_apps(query, limit)	インストール済みのアプリバンドルを一覧表示します。名前またはバンドル ID で絞り込むこともできます。
ios_resolve_app_container(bundleId)	バンドル ID から .app バンドル、アプリのデータコンテナ、表示可能な場合はアプリグループのコンテナを特定します。
ios_list_preferences(bundleId)	アプリのデータコンテナにある Library/Preferences フォルダー内の plist ファイルを一覧表示します。
ios_read_preferences(bundleId, includeAll, maxFiles)	アプリの設定 plist ファイルを読み取ります。既定では、バンドル ID と完全に一致する plist ファイルのみを読み取ります。

SQLite

ツール	機能
ios_read_sqlite_schema(path)	SQLite データベースからテーブル／ビュー名、SQL 定義、テーブル列を読み取ります。
ios_query_sqlite(path, sql, limit)	読み取り専用の SQL ステートメントを 1 つ実行し、行数を制限して返します。SELECT、PRAGMA、WITH、EXPLAIN を使用できます。

React Native バンドル

通常の React Native .jsbundle ファイルは JavaScript のテキストです。ios_decode_js_bundle を使うと整形でき、結果を MCP のレスポンスでプレビューするか、ローカルファイルに保存できます。

Hermes バンドルはバイトコードです。サーバーはこれを検出し、hbc-decompiler、hbc-disassembler、hermesc、hbctool のいずれかが PATH 上にあれば、自動的に使用できます。出力は通常、疑似コード、HASM、またはバイトコード／逆アセンブル結果であり、元のソースコードではありません。

デコードに失敗した場合は、ios_list_hermes_decoders() を実行してください。MCP サーバー自身のプロセスから確認できる内容が表示されます。

オプションのデコーダーヘルパー：

npx -p github:xtofuub/ios-files-mcp ios-files-mcp-install-hermes-dec
npx -p github:xtofuub/ios-files-mcp ios-files-mcp-check-hermes-decoders

radare2 静的解析ツール

デフォルトでは、これらのツールは iOS デバイス上の radare2 を検出し、SSH 経由でデバイス上で実行します。バイナリをコピーする必要はありません。デバイスに r2 がインストールされていない場合、MCP はバイナリを一時的なローカルフォルダーにコピーしたうえで、コンピューター上で r2／rabin2 を実行します。ios_r2_check を実行すると、どちらの実行方法が有効か確認できます。

推奨インストール方法（Sileo を使用して iOS デバイスにインストール）：

1. 脱獄済みデバイスで Sileo を開きます。
2. Procursus リポジトリから radare2 パッケージをインストールします（Dopamine や palera1n など、最近の脱獄環境ではデフォルトで利用できます）。
3. コンピューターから ssh mobile@<device-ip> 'r2 -v' を実行して、インストールを確認します。

Sileo でインストールした場合の、デバイス上の一般的なパス：

/usr/bin/r2          (rootful jailbreaks: unc0ver, checkra1n, classic palera1n)
/var/jb/usr/bin/r2   (rootless jailbreaks: Dopamine, palera1n rootless)

MCP は SSH 経由で command -v r2 を実行するため、デバイスの $PATH にあるバイナリが使われます。標準以外の場所にバイナリがある場合は、IOS_FILES_MCP_R2_DEVICE_R2_PATH=/your/path でパスを指定できます。

モード：

• IOS_FILES_MCP_R2_MODE=auto（デフォルト）— まずデバイス上で試し、失敗した場合はローカルに切り替えます。
• IOS_FILES_MCP_R2_MODE=device — デバイス上の r2 が必須になります。見つからない場合は直ちに失敗します。
• IOS_FILES_MCP_R2_MODE=local — 常にこのコンピューター上で実行します（バイナリを一時フォルダーにコピーします）。

任意の環境変数：

IOS_FILES_MCP_ENABLE_R2=true
IOS_FILES_MCP_R2_MODE=auto
IOS_FILES_MCP_R2_DEVICE_R2_PATH=/var/jb/usr/bin/r2
IOS_FILES_MCP_R2_DEVICE_RABIN2_PATH=/var/jb/usr/bin/rabin2
IOS_FILES_MCP_R2_PATH=r2
IOS_FILES_MCP_RABIN2_PATH=rabin2
IOS_FILES_MCP_R2_TIMEOUT_MS=30000
IOS_FILES_MCP_R2_MAX_OUTPUT_BYTES=16777216
IOS_FILES_MCP_R2_MAX_BINARY_SIZE=134217728

移行に関する注意：以前のホスト側インストーラー（ios-files-mcp-install-radare2）と、IOS_FILES_MCP_INSTALL_R2 postinstall フラグは削除されました。Sileo を使って iOS デバイスに radare2 をインストールするか、IOS_FILES_MCP_R2_MODE=local を使う場合は、任意のパッケージマネージャーを使ってローカルにインストールしてください。

用途：

• インストール済みアプリの概要をすばやく確認するには、ios_r2_app_triage(bundleId) を使います。
• バイナリのパスがすでにわかっている場合は、ios_r2_binary_info(remotePath) を使います。
• エンドポイント、シークレット、Firebase、URL、デバッグ文字列、機能フラグを調べるには、ios_r2_strings(remotePath, query, limit) を使います。
• Keychain、暗号、ネットワーク、SQLite、WebKit、デバイス整合性、アンチデバッグチェックなどのフレームワーク／API の使用状況を調べるには、ios_r2_imports(remotePath, query, limit) を使います。
• 利用可能な関数を一覧化するには、ios_r2_functions(remotePath, limit) を使います。
• 選択した関数またはアドレスを調べるには、ios_r2_function_disasm(remotePath, functionNameOrAddress) を使います。

推奨する解析手順：

1. ios_find_app("App Name") または ios_resolve_app_container("com.example.app")
2. ios_r2_app_triage("com.example.app")
3. http、api、firebase、token、auth、key、debug などのクエリを使って ios_r2_strings(remotePath, query, limit) を実行します。
4. SecItem、CommonCrypto、CryptoKit、NSURLSession、SQLite、WKWebView などのクエリを使って ios_r2_imports(remotePath, query, limit) を実行します。
5. ios_r2_functions(remotePath, limit)
6. 特定の興味深い関数またはアドレスに対して ios_r2_function_disasm(remotePath, functionNameOrAddress) を実行します。

ツール	機能
ios_r2_check()	r2 のサポートが有効かどうか、およびローカルで r2／rabin2 を利用できるかどうかを表示します。
ios_r2_binary_info(remotePath)	1 つのバイナリパスについて、Mach-O メタデータとリンク済みライブラリを返します。
ios_r2_app_triage(bundleId)	インストール済みアプリを解決して実行ファイルを見つけ、バイナリ情報、注目すべきインポート／文字列、関数のプレビュー、および次のアクションを返します。
ios_r2_strings(remotePath, query, limit)	バイナリ内の文字列を検索し、URL、エンドポイント、トークン、Firebase 設定、デバッグテキスト、機能フラグを探します。
ios_r2_imports(remotePath, query, limit)	Keychain、暗号、ネットワーク、SQLite、WebKit、アンチデバッグ呼び出しなどのインポート済みシンボル／フレームワーク API を検索します。
ios_r2_functions(remotePath, limit)	詳細な調査に先立ち、関数名とアドレスを一覧表示します。
ios_r2_function_disasm(remotePath, functionNameOrAddress)	選択した 1 つの関数またはアドレスの逆アセンブル結果を、構造化された JSON で返します。

ファイルの書き込み

これらのツールは、readOnly=false かつ allowWrites=true の場合にのみ有効になります。

ツール	機能
ios_write_file(path, content)	UTF-8 の内容をファイルに書き込みます。backupBeforeWrite=true の場合、既存のファイルはバックアップされます。
ios_append_file(path, content)	UTF-8 の内容をファイルに追記します。ファイルが存在しない場合は作成します。
ios_delete_file(path)	ファイルまたは空のディレクトリを削除します。
ios_move_file(from, to)	ファイルを移動または名前変更します。設定されている場合、既存の移動先はバックアップされます。
ios_copy_file(from, to)	iOS デバイス上のファイルをコピーします。設定されている場合、既存のコピー先はバックアップされます。
ios_mkdir(path)	ディレクトリを作成します。

書き込み可能なツールでは、オプションの approvalId も指定できます。requireWriteApproval=true の場合、最初の呼び出しでは承認リクエストが返され、書き込みは行われません。対象の操作を正確に承認した後にのみ、返された approvalId を指定して同じツールを再実行してください。

診断

ツール	機能
ios_doctor()	SSH/SFTP 接続、表示可能なアプリのルート、ローカルのエクスポートフォルダー、MCP 設定、Hermes デコーダーの利用可否など、セットアップの問題を検出します。
ios_connection_doctor()	SSH/SFTP 接続、表示可能なルート、ローカルの成果物ルート、MCP 設定、Hermes デコーダーの利用可否を確認します。
ios_config()	Codex、Claude、OpenCode、VS Code がこの MCP サーバーを正しく起動するように設定されているかを確認します。
ios_mcp_config_status()	Codex、Claude、OpenCode、VS Code の設定ファイルに、想定される ios-files サーバーエントリが含まれているかを表示します。
ios_app(bundleId)	バンドルのパス、データコンテナ、アプリグループ、Info.plist の概要、環境設定ファイル、SQLite ファイル、JS バンドルなど、アプリの概要をすばやく表示します。
ios_snapshot_app(bundleId)	バンドル／データ／アプリグループのパス、Info.plist の概要、環境設定ファイル、SQLite ファイル、JS バンドルなど、メタデータを中心としたアプリのスナップショットを作成します。
ios_diagnose_roots()	現在の SSH/SFTP ログインで一般的な iOS アプリのルートにアクセスできるかを確認し、空のディレクトリについて説明を表示します。

注意事項

• 再ビルド後に MCP クライアントを再起動してください。
• mobile としてログインしたときにディレクトリが空の場合、デバイスでそれらのディレクトリが root にしか公開されていない可能性があるため、SSH/SFTP で root として接続してみてください。
• ios_search_files は再帰的に検索するため、SFTP 経由では時間がかかることがあります。アプリには ios_find_app、ios_list_apps、または ios_resolve_app_container を使用してください。
• ios_search_files は、デフォルトで結果数に上限があり、キャッシュされます。同じ検索を繰り返すと、searchCacheTtlMs の期間中はメモリから結果が返されます。
• まず maxResults=10 や maxDepth=2 などを指定して、再帰検索の範囲を小さくしてください。
• ios_search_files は、デフォルトで簡潔なパス／種類の結果を返します。サイズと更新日時が必要な場合にのみ、includeMetadata=true を設定してください。
• ios_read_file は、maxReadSize によりデフォルトで 4 MiB の上限が適用されます。
• ファイル全体の読み取りを繰り返す代わりに、ios_read_file_chunk、ios_tail_file、または ios_read_last_lines を使用してください。
• 大きなファイルを 1 つ取得する場合は ios_download_file を、iOS デバイスからコンピューターにコピーするフォルダーや複数のファイルを取得する場合は ios_zip_download を使用してください。
• データベースファイル全体をチャットにダンプする代わりに、読み取り専用の SQLite 検査には ios_read_sqlite_schema と ios_query_sqlite を使用してください。
• React Native バンドルがプレーンな JavaScript か Hermes バイトコードか判断できない場合は、ios_decode_js_bundle の前に ios_inspect_js_bundle を使用してください。
• アプリの検索方法の詳細は SKILLS.md に記載されています。