Ios Files

ios-files-mcp

用于受控 SSH/SFTP 访问 iOS 设备文件系统的 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]

运行适用于你的编码 Agent 的命令。将 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)	列出一个目录中的文件和文件夹。
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 bundle 是纯 JavaScript、Hermes 字节码还是未知二进制文件。
ios_decode_js_bundle(path, mode, localPath, maxOutputBytes, beautify)	美化纯 .jsbundle 文件，或为字节码 bundle 运行已配置的 Hermes 解码器。
ios_list_hermes_decoders()	显示已配置的解码器、自动检测到的解码器命令和设置说明。

将文件复制到电脑

工具	功能
ios_download_file(remotePath, localPath, overwrite)	将一个文件从 iOS 设备复制到电脑上允许的本地文件夹。不受 maxReadSize 限制。
ios_zip_download(paths, localPath, overwrite)	创建一个本地 ZIP 文件，其中包含一个或多个 iOS 设备上的文件或文件夹。适用于应用文件夹、日志或多个文件的打包导出。

localPath 必须位于 localArtifactRoots 内。

App Store 应用辅助工具

工具	功能
ios_find_app(query)	根据显示名称、.app 名称或 bundle id 查找已安装的应用，无需进行耗时的递归搜索。
ios_list_apps(query, limit)	列出已安装的应用 bundle，可按名称或 bundle id 筛选。
ios_resolve_app_container(bundleId)	将 bundle id 解析为其 .app bundle、应用数据容器，以及可见时的应用组容器。
ios_list_preferences(bundleId)	列出应用数据容器 Library/Preferences 文件夹中的 plist 文件。
ios_read_preferences(bundleId, includeAll, maxFiles)	读取应用偏好设置 plist 文件。默认只读取与 bundle id 完全匹配的 plist。

SQLite

工具	功能
ios_read_sqlite_schema(path)	读取 SQLite 数据库中的表和视图名称、SQL 定义及表列。
ios_query_sqlite(path, sql, limit)	执行一条只读 SQL 语句并返回有限行数的结果。允许使用 SELECT、PRAGMA、WITH 和 EXPLAIN。

React Native Bundles

纯 React Native .jsbundle 文件是 JavaScript 文本。ios_decode_js_bundle 可以对其进行美化，并在 MCP 响应中预览结果或将结果保存到本地文件。

Hermes bundle 是字节码。若 PATH 中存在 hbc-decompiler、hbc-disassembler、hermesc 或 hbctool，服务便可以检测并自动使用它们。输出通常是伪代码、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 查看当前启用的运行方式。

推荐安装方式（在 iOS 设备上通过 Sileo 安装）：

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 安装后标志已移除。请通过 Sileo 在 iOS 设备上安装 radare2；如果希望使用 IOS_FILES_MCP_R2_MODE=local，也可以通过你自己的包管理器在本地安装。

使用场景：

• 使用 ios_r2_app_triage(bundleId) 快速查看已安装应用的概况。
• 已知二进制文件路径时，使用 ios_r2_binary_info(remotePath)。
• 使用 ios_r2_strings(remotePath, query, limit) 搜索端点、机密信息、Firebase、URL、调试字符串和功能标志。
• 使用 ios_r2_imports(remotePath, query, limit) 搜索框架/API 的使用情况，例如 Keychain、加密、网络、SQLite、WebKit、设备完整性和反调试检查。
• 使用 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)	返回指定二进制文件路径的 Mach-O 元数据和链接库。
ios_r2_app_triage(bundleId)	解析已安装的应用，查找其可执行文件，并返回二进制信息、有意义的导入项/字符串、函数预览和后续操作建议。
ios_r2_strings(remotePath, query, limit)	搜索二进制字符串中的 URL、端点、令牌、Firebase 配置、调试文本和功能标志。
ios_r2_imports(remotePath, query, limit)	搜索导入的符号/框架 API，例如 Keychain、加密、网络、SQLite、WebKit 和反调试调用。
ios_r2_functions(remotePath, limit)	列出函数名称和地址，供后续深入检查。
ios_r2_function_disasm(remotePath, functionNameOrAddress)	返回所选函数或地址的结构化 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 访问这些目录，请尝试以 root 用户身份使用 SSH/SFTP。
• 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，而不要反复读取整个文件。
• 如果要从 iOS 设备向电脑复制单个大文件，请使用 ios_download_file；如果要复制文件夹或多个文件，请使用 ios_zip_download。
• 只读检查 SQLite 时，请使用 ios_read_sqlite_schema 和 ios_query_sqlite，而不要将整个数据库文件转储到聊天中。
• 如果不确定 React Native 包是纯 JavaScript 还是 Hermes 字节码，请先使用 ios_inspect_js_bundle，再使用 ios_decode_js_bundle。
• 更多应用查找指南请参阅 SKILLS.md。