iOS Simulator MCP 服务端配置实战一次搞定路径、输出与工具裁剪【免费下载链接】ios-simulator-mcpMCP server for interacting with the iOS simulator项目地址: https://gitcode.com/gh_mirrors/io/ios-simulator-mcpios-simulator-mcp 是一个基于 MCPModel Context Protocol的服务端程序它把 iOS 模拟器变成 AI 助手可以亲手操作的测试环境——截图、点按、输入文字、安装和启动 App全部能靠自然语言指令完成。这篇文章不打算复述官方文档而是从一次真实的翻车现场出发带你用三个环境变量把路径、输出、工具三件事一次理顺并附上可复制的完整配置模板和自检方法。先讲一个翻车现场截图去哪了只有天知道上周你让 AI 在模拟器里做一轮 UI 回归验证它的回复是截图已保存请查收。 你翻遍了桌面和项目目录最后在~/Downloads里找到一张和三百张旧截图混在一起的 PNG——文件名是时间戳根本不知道对应哪一步操作。这还算温柔的。更常见的是这三种事故启动时报idb: command not found因为 IDB 装在了一个非标准位置服务端在PATH里找不到它AI 一股脑调用record_video、stop_recording这类你根本用不上的录制工具工具列表又长又乱误操作概率直线上升模拟器开了三台AI 分不清该操作哪台UI 点到了错误设备的屏幕上。好消息是这三类问题在 ios-simulator-mcp 里都预留了对应的配置开关而且总共只有三个环境变量加一个可选参数。下面先给你一份抄了就能跑的底稿。抄了就能跑30 秒最小可用配置如果你用的是 Cursor编辑~/.cursor/mcp.json写入下面这段这是最小可用版后面每一项都会被展开讲{ mcpServers: { ios-simulator: { command: npx, args: [-y, ios-simulator-mcp] } } }重启 Cursor然后在对话里输入Get the currently booted simulator ID如果返回了类似Booted Simulator: iPhone 15 Pro. UUID: 37A360EC-...的结果说明服务端已经连通。先跑起来再去谈优化——接下来这三张王牌就是让它在真实项目里指哪打哪的关键。三张王牌逐个拆解每个配置为什么存在、何时用、改了会怎样王牌一路径类配置把 IDB 从犄角旮旯里捞出来ios-simulator-mcp 的所有 UI 操作点按、滑动、输入、读取无障碍树都走 Facebook 的 IDB 工具服务端默认从环境变量PATH里找idb命令。问题在于IDB 用 pip 安装后可执行文件往往落在~/.local/bin这种不一定在PATH里的目录于是服务端启动后第一次调用 UI 工具就报错。这时用IOS_SIMULATOR_MCP_IDB_PATH显式指路export IOS_SIMULATOR_MCP_IDB_PATH~/.local/bin/idb⚠️ 注意这个变量不是随便填的。服务端在读取它时会做两件事——先展开开头的~/再用文件系统校验路径是否真实存在。写错了不会稍后再报而是启动阶段直接抛错Custom IDB path specified in IOS_SIMULATOR_MCP_IDB_PATH does not exist。这条报错文案反而是你判断变量有没有被读取到的最好证据。❌ 错误写法凭印象写一个可能存在的路径指望它能用就行。 ✅ 推荐写法先which idb或type -a idb确认真实位置再把完整路径填进去确认过在PATH里的干脆不设这个变量。王牌二输出类配置给截图和录像一个固定归宿screenshot工具的output_path是必填参数而record_video不传路径时会自动生成simulator_recording_时间戳.mp4这样的文件名。问题来了这两个工具在解析相对路径时都遵循同一条规则——拼到IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR指定的目录下如果这个变量没设置就全部落到~/Downloads。这就是开篇那个截图找不到事故的根源。解法是给所有产物指定一个专属目录{ mcpServers: { ios-simulator: { command: npx, args: [-y, ios-simulator-mcp], env: { IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR: ~/code/awesome-project/tmp } } } }配置之后AI 只要说截图保存为 login.png文件就会出现在~/code/awesome-project/tmp/login.png而不是淹没在下载目录里。路径解析的优先级可以记成一句话你传的是绝对路径 → 直接用以~/开头 → 展开成家目录下的绝对路径其余相对路径 → 拼接到IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR该变量未设置 → 退回~/Downloads。 小技巧如果你需要截图长期归档与其让 AI 每次都写绝对路径不如把默认目录设成一个带日期前缀的项目目录例如~/artifacts/2026-08这样截图保存为 xxx.png这类指令天然归档不需要额外叮嘱。王牌三开关类配置给 AI 的工具箱做减法服务端默认注册了十几个工具从get_booted_sim_id到install_app一应俱全。但你的项目可能永远用不到视频录制或者出于安全考虑不想让 AI 随意安装 App。IOS_SIMULATOR_MCP_FILTERED_TOOLS就是干这个的——用逗号分隔列出要拉黑的工具名服务端启动时根本不会注册它们IOS_SIMULATOR_MCP_FILTERED_TOOLSrecord_video,stop_recording,install_app,launch_app两个细节决定它好不好用逗号两侧允许有空格服务端会先trim再匹配匹配是精确的工具名大小写不能错。写错一个字母等于白配被过滤的工具照样出现在列表里。想裁剪得准确先背熟这份完整工具名清单类别工具名设备与启动get_booted_sim_id、open_simulatorUI 操作ui_tap、ui_swipe、ui_type、ui_describe_all、ui_describe_point、ui_find_element、ui_view输出采集screenshot、record_video、stop_recording应用管理install_app、launch_app、terminate_app、list_apps链接跳转open_url比如你只想保留 UI 验证链路可以配成record_video,stop_recording,install_app,launch_app,terminate_app,open_url剩下的就是一套精简的点、滑、读、截工具箱。附加一张隐藏牌多模拟器场景下别点错屏幕绝大多数工具都接受一个可选的udid参数不传时服务端会自动去找当前已启动的那台模拟器。问题是已启动可能不止一台。两条路可以指定目标每次调用时显式传udid格式必须是 8-4-4-4-12 的十六进制 UUID不符合会被参数校验直接拒绝设置环境变量IDB_UDID统一指定所有没传udid的调用都会走它。export IDB_UDID37A360EC-75F9-4AEC-8EFA-10F4A58D8CCA 小技巧拿不准当前是哪台设备先让 AI 调用get_booted_sim_id把返回的 UUID 回填进IDB_UDID一劳永逸。生产级完整模板两个主流客户端各来一份Cursor 用户把三张王牌写进~/.cursor/mcp.json{ mcpServers: { ios-simulator: { command: npx, args: [-y, ios-simulator-mcp], env: { IOS_SIMULATOR_MCP_IDB_PATH: ~/.local/bin/idb, IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR: ~/code/awesome-project/tmp, IOS_SIMULATOR_MCP_FILTERED_TOOLS: record_video,stop_recording,install_app, IDB_UDID: 37A360EC-75F9-4AEC-8EFA-10F4A58D8CCA } } } }保存后彻底重启 Cursor不是刷新窗口环境变量会在服务端进程启动时一次性读入。Claude Code 用户一条命令搞定claude mcp add ios-simulator npx ios-simulator-mcp \ -e IOS_SIMULATOR_MCP_IDB_PATH~/.local/bin/idb \ -e IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR~/code/awesome-project/tmp \ -e IOS_SIMULATOR_MCP_FILTERED_TOOLSrecord_video,stop_recording如果-e参数在你的版本里不可用也可以直接编辑 Claude Code 的 MCP 配置文件把上面的env块原样写进去效果一致。本地开发模式改源码调试时怎么配想边改代码边验证或者对网络安装不放心可以走本地构建git clone https://gitcode.com/gh_mirrors/io/ios-simulator-mcp cd ios-simulator-mcp npm install npm run build然后把客户端配置里的命令从npx换成node参数指向构建产物{ mcpServers: { ios-simulator: { command: node, args: [/绝对路径/ios-simulator-mcp/build/index.js], env: { } } } }⚠️ 注意本地模式需要 Node.js 20 及以上版本package.json里的engines字段写得很清楚。网上很多老教程写Node 14 即可那是早期版本的旧闻照抄会卡在依赖安装上。配置完怎么确认真的生效三个自检动作配置这东西最怕配了等于没配。三个动作帮你验证每个都有明确的生效证据看工具清单重启客户端后打开 MCP 工具列表。你过滤掉的record_video、stop_recording不应该再出现——这就是IOS_SIMULATOR_MCP_FILTERED_TOOLS生效的铁证。Claude Code 可以用claude mcp list查看连接状态。跑一次最小调用让 AI 执行截图保存为 verify.png然后去你设置的DEFAULT_OUTPUT_DIR目录里找这个文件。找到了说明输出路径映射生效文件出现在~/Downloads说明变量没被读进去检查一下是不是改错了客户端配置文件。故意踩一次错把IOS_SIMULATOR_MCP_IDB_PATH临时改成一个不存在的路径再启动如果能看到那条does not exist的报错说明路径变量确实被服务端读取了——报错本身就是配置生效的证明。测试完记得改回来。高频失误清单为什么错比怎么修更重要Node 版本卡在 14/16项目要求 20。这不是兼容性问题而是依赖解析阶段就会失败的硬门槛。老教程害人先node -v再动手。IDB 路径写成可能存在的路径服务端启动时用fs.existsSync校验路径不存在会立刻抛错。所以配之前先type -a idb拿到真身而不是赌运气。工具名拼写不一致FILTERED_TOOLS是精确匹配加首尾去空格不区分大小写不它区分。Record_Video过滤不掉record_video等于白配。用上面那份清单做复制粘贴别手打。只在 shell 里export就以为完事GUI 启动的 MCP 客户端不一定继承你终端的 shell 环境。变量要写进客户端的env配置块才真正属于服务端进程。模拟器没 boot 就开跑所有 UI 工具在找不到已启动设备时都会返回No booted simulator found。先手动开一台或用get_booted_sim_id确认。拿截图尺寸当坐标单位截图是 3x 分辨率而ui_tap、ui_swipe用的是 point 坐标。按截图像素数点坐标八成点偏。用ui_describe_point先探坐标再操作能省一轮返工。延伸资源从会用走向用熟配置只是入门想把这套东西用出生产力项目仓库里这几份文档值得按顺序翻README.md全部 17 个工具的参数说明与 Prompt 示例配环境变量时对照着查TROUBLESHOOTING.mdIDB 在 Homebrew、asdf 两种环境下的完整安装路径Python 环境混乱时照它走最稳QA.md手工测试用例清单改完本地代码想验证行为是否正常照着逐条过一遍src/index.ts整个服务端只有这一个文件环境变量在哪里被读取、路径怎么解析源码里一眼就能看完比任何文档都准确CONTEXT.mdMCP 协议、simctl、IDB 命令的参考索引写自定义工具时的案头手册。三个环境变量一张工具清单一份自检清单——到此为止你的 ios-simulator-mcp 已经从能用升级到顺手。下次 AI 再跟你说截图已保存你知道它一定保存在你指定的那个目录里。【免费下载链接】ios-simulator-mcpMCP server for interacting with the iOS simulator项目地址: https://gitcode.com/gh_mirrors/io/ios-simulator-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考