xcode

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xcode Build MCP

Build, test, run, and manage Xcode projects and Swift packages via the XcodeBuildMCP server.

通过XcodeBuildMCP服务器构建、测试、运行和管理Xcode项目与Swift包。

When to Use

使用场景

User wants to build an iOS/macOS/watchOS/tvOS/visionOS app
User wants to run tests on simulator or device
User wants to launch an app on simulator or device
User mentions "xcodebuild", "swift build", "swift test"
User wants to scaffold a new iOS/macOS project
User wants to interact with iOS simulator (tap, type, screenshot)
User wants to capture logs from simulator or device
User wants to discover Xcode projects in a directory

用户想要构建iOS/macOS/watchOS/tvOS/visionOS应用
用户想要在模拟器或设备上运行测试
用户想要在模拟器或设备上启动应用
用户提及"xcodebuild"、"swift build"、"swift test"
用户想要搭建新的iOS/macOS项目
用户想要与iOS模拟器交互（点击、输入、截图）
用户想要捕获模拟器或设备的日志
用户想要发现目录中的Xcode项目

Quick Reference

快速参考

All tools are called via mcporter using the XcodeBuildMCP server:

bash

bunx mcporter call --stdio "xcodebuildmcp" <tool_name> [args...]

Assumes

mcporter

and

xcodebuildmcp

are installed globally;

bunx

runs the installed binaries and does not fetch them.

所有工具都通过mcporter调用XcodeBuildMCP服务器：

bash

bunx mcporter call --stdio "xcodebuildmcp" <tool_name> [args...]

假设

mcporter

和

xcodebuildmcp

已全局安装；

bunx

会运行已安装的二进制文件，不会重新获取。

Session Defaults (IMPORTANT - Set First!)

会话默认设置（重要 - 首先设置！）

Before using most build/test tools, you MUST set session defaults:

bash

bunx mcporter call --stdio "xcodebuildmcp" session-set-defaults \
  projectPath="/path/to/Project.xcodeproj" \
  scheme="MyApp" \
  simulatorName="iPhone 16"

Or for a workspace:

bash

bunx mcporter call --stdio "xcodebuildmcp" session-set-defaults \
  workspacePath="/path/to/Project.xcworkspace" \
  scheme="MyApp" \
  simulatorId="DEVICE_UDID"

Check current defaults:

bash

bunx mcporter call --stdio "xcodebuildmcp" session-show-defaults

Clear defaults:

bash

bunx mcporter call --stdio "xcodebuildmcp" session-clear-defaults all=true

在使用大多数构建/测试工具之前，你必须设置会话默认值：

bash

bunx mcporter call --stdio "xcodebuildmcp" session-set-defaults \
  projectPath="/path/to/Project.xcodeproj" \
  scheme="MyApp" \
  simulatorName="iPhone 16"

或者针对工作区：

bash

bunx mcporter call --stdio "xcodebuildmcp" session-set-defaults \
  workspacePath="/path/to/Project.xcworkspace" \
  scheme="MyApp" \
  simulatorId="DEVICE_UDID"

查看当前默认值：

bash

bunx mcporter call --stdio "xcodebuildmcp" session-show-defaults

清除默认值：

bash

bunx mcporter call --stdio "xcodebuildmcp" session-clear-defaults all=true

Discovery Tools

发现工具

Find Xcode Projects

查找Xcode项目

bash

bunx mcporter call --stdio "xcodebuildmcp" discover_projs workspaceRoot="$(pwd)"

bash

bunx mcporter call --stdio "xcodebuildmcp" discover_projs workspaceRoot="$(pwd)"

List Schemes

列出Scheme

bash

bunx mcporter call --stdio "xcodebuildmcp" list_schemes

bash

bunx mcporter call --stdio "xcodebuildmcp" list_schemes

Doctor (Check Environment)

环境检查（Doctor）

bash

bunx mcporter call --stdio "xcodebuildmcp" doctor

bash

bunx mcporter call --stdio "xcodebuildmcp" doctor

Simulator Tools

模拟器工具

List Simulators

列出模拟器

bash

bunx mcporter call --stdio "xcodebuildmcp" list_sims

bash

bunx mcporter call --stdio "xcodebuildmcp" list_sims

Boot Simulator

启动模拟器

bash

bunx mcporter call --stdio "xcodebuildmcp" boot_sim

bash

bunx mcporter call --stdio "xcodebuildmcp" boot_sim

Open Simulator App

打开模拟器应用

bash

bunx mcporter call --stdio "xcodebuildmcp" open_sim

bash

bunx mcporter call --stdio "xcodebuildmcp" open_sim

Build for Simulator

为模拟器构建应用

bash

bunx mcporter call --stdio "xcodebuildmcp" build_sim

bash

bunx mcporter call --stdio "xcodebuildmcp" build_sim

Build and Run on Simulator

构建并在模拟器上运行

bash

bunx mcporter call --stdio "xcodebuildmcp" build_run_sim

bash

bunx mcporter call --stdio "xcodebuildmcp" build_run_sim

Run Tests on Simulator

在模拟器上运行测试

bash

bunx mcporter call --stdio "xcodebuildmcp" test_sim

bash

bunx mcporter call --stdio "xcodebuildmcp" test_sim

Get Built App Path (Simulator)

获取已构建应用的路径（模拟器）

bash

bunx mcporter call --stdio "xcodebuildmcp" get_sim_app_path platform="iOS Simulator"

bash

bunx mcporter call --stdio "xcodebuildmcp" get_sim_app_path platform="iOS Simulator"

Install App on Simulator

在模拟器上安装应用

bash

bunx mcporter call --stdio "xcodebuildmcp" install_app_sim appPath="/path/to/App.app"

bash

bunx mcporter call --stdio "xcodebuildmcp" install_app_sim appPath="/path/to/App.app"

Launch App on Simulator

在模拟器上启动应用

bash

bunx mcporter call --stdio "xcodebuildmcp" launch_app_sim bundleId="com.example.MyApp"

bash

bunx mcporter call --stdio "xcodebuildmcp" launch_app_sim bundleId="com.example.MyApp"

Stop App on Simulator

在模拟器上停止应用

bash

bunx mcporter call --stdio "xcodebuildmcp" stop_app_sim bundleId="com.example.MyApp"

bash

bunx mcporter call --stdio "xcodebuildmcp" stop_app_sim bundleId="com.example.MyApp"

Simulator UI Automation

模拟器UI自动化

Take Screenshot

截图

bash

bunx mcporter call --stdio "xcodebuildmcp" screenshot

bash

bunx mcporter call --stdio "xcodebuildmcp" screenshot

Describe UI (Get View Hierarchy)

描述UI（获取视图层级）

Gets precise frame coordinates for all visible elements - USE THIS before any UI interactions:

bash

bunx mcporter call --stdio "xcodebuildmcp" describe_ui

获取所有可见元素的精确坐标 - 在进行任何UI交互前请使用此工具：

bash

bunx mcporter call --stdio "xcodebuildmcp" describe_ui

Tap

点击

bash

undefined

bash

undefined

Tap by coordinates (use describe_ui first to get coordinates)

通过坐标点击（先使用describe_ui获取坐标）

bunx mcporter call --stdio "xcodebuildmcp" tap x=100 y=200

Tap by accessibility ID

通过辅助功能ID点击

bunx mcporter call --stdio "xcodebuildmcp" tap id="myButton"

Tap by label

通过标签点击

bunx mcporter call --stdio "xcodebuildmcp" tap label="Submit"

undefined

bunx mcporter call --stdio "xcodebuildmcp" tap label="Submit"

undefined

Long Press

长按

bash

bunx mcporter call --stdio "xcodebuildmcp" long_press x=100 y=200 duration=1000

bash

bunx mcporter call --stdio "xcodebuildmcp" long_press x=100 y=200 duration=1000

Swipe

滑动

bash

bunx mcporter call --stdio "xcodebuildmcp" swipe x1=100 y1=400 x2=100 y2=100

bash

bunx mcporter call --stdio "xcodebuildmcp" swipe x1=100 y1=400 x2=100 y2=100

Gesture Presets

预设手势

bash

bunx mcporter call --stdio "xcodebuildmcp" gesture preset="scroll-down"

bash

bunx mcporter call --stdio "xcodebuildmcp" gesture preset="scroll-down"

Presets: scroll-up, scroll-down, scroll-left, scroll-right,

预设选项：scroll-up, scroll-down, scroll-left, scroll-right,

swipe-from-left-edge, swipe-from-right-edge,

swipe-from-top-edge, swipe-from-bottom-edge

undefined

undefined

Type Text

输入文本

bash

bunx mcporter call --stdio "xcodebuildmcp" type_text text="Hello World"

bash

bunx mcporter call --stdio "xcodebuildmcp" type_text text="Hello World"

Press Button

按下按钮

bash

bunx mcporter call --stdio "xcodebuildmcp" button buttonType="home"

bash

bunx mcporter call --stdio "xcodebuildmcp" button buttonType="home"

Types: apple-pay, home, lock, side-button, siri

按钮类型：apple-pay, home, lock, side-button, siri

undefined

undefined

Key Press

按键

bash

bunx mcporter call --stdio "xcodebuildmcp" key_press keyCode=40  # Return key

bash

bunx mcporter call --stdio "xcodebuildmcp" key_press keyCode=40  # 返回键

Common: 40=Return, 42=Backspace, 43=Tab, 44=Space

常用键码：40=Return, 42=Backspace, 43=Tab, 44=Space

undefined

undefined

Simulator Settings

模拟器设置

Set Appearance (Dark/Light Mode)

设置外观（深色/浅色模式）

bash

bunx mcporter call --stdio "xcodebuildmcp" set_sim_appearance mode="dark"

bash

bunx mcporter call --stdio "xcodebuildmcp" set_sim_appearance mode="dark"

Set Location

设置位置

bash

bunx mcporter call --stdio "xcodebuildmcp" set_sim_location latitude=37.7749 longitude=-122.4194

bash

bunx mcporter call --stdio "xcodebuildmcp" set_sim_location latitude=37.7749 longitude=-122.4194

Reset Location

重置位置

bash

bunx mcporter call --stdio "xcodebuildmcp" reset_sim_location

bash

bunx mcporter call --stdio "xcodebuildmcp" reset_sim_location

Set Status Bar Network

设置状态栏网络

bash

bunx mcporter call --stdio "xcodebuildmcp" sim_statusbar dataNetwork="5g"

bash

bunx mcporter call --stdio "xcodebuildmcp" sim_statusbar dataNetwork="5g"

Options: clear, hide, wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc

选项：clear, hide, wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc

undefined

undefined

Erase Simulator

重置模拟器

bash

bunx mcporter call --stdio "xcodebuildmcp" erase_sims shutdownFirst=true

bash

bunx mcporter call --stdio "xcodebuildmcp" erase_sims shutdownFirst=true

Simulator Log Capture

模拟器日志捕获

Start Log Capture

开始日志捕获

bash

bunx mcporter call --stdio "xcodebuildmcp" start_sim_log_cap bundleId="com.example.MyApp"

bash

bunx mcporter call --stdio "xcodebuildmcp" start_sim_log_cap bundleId="com.example.MyApp"

Returns a logSessionId

返回一个logSessionId

undefined

undefined

Stop Log Capture

停止日志捕获

bash

bunx mcporter call --stdio "xcodebuildmcp" stop_sim_log_cap logSessionId="SESSION_ID"

bash

bunx mcporter call --stdio "xcodebuildmcp" stop_sim_log_cap logSessionId="SESSION_ID"

Video Recording

视频录制

Start Recording

开始录制

bash

bunx mcporter call --stdio "xcodebuildmcp" record_sim_video start=true

bash

bunx mcporter call --stdio "xcodebuildmcp" record_sim_video start=true

Stop Recording

停止录制

bash

bunx mcporter call --stdio "xcodebuildmcp" record_sim_video stop=true outputFile="/path/to/output.mp4"

bash

bunx mcporter call --stdio "xcodebuildmcp" record_sim_video stop=true outputFile="/path/to/output.mp4"

Physical Device Tools

物理设备工具

List Connected Devices

列出已连接设备

bash

bunx mcporter call --stdio "xcodebuildmcp" list_devices

bash

bunx mcporter call --stdio "xcodebuildmcp" list_devices

Build for Device

为设备构建应用

bash

bunx mcporter call --stdio "xcodebuildmcp" build_device

bash

bunx mcporter call --stdio "xcodebuildmcp" build_device

Test on Device

在设备上运行测试

bash

bunx mcporter call --stdio "xcodebuildmcp" test_device

bash

bunx mcporter call --stdio "xcodebuildmcp" test_device

Install App on Device

在设备上安装应用

bash

bunx mcporter call --stdio "xcodebuildmcp" install_app_device appPath="/path/to/App.app"

bash

bunx mcporter call --stdio "xcodebuildmcp" install_app_device appPath="/path/to/App.app"

Launch App on Device

在设备上启动应用

bash

bunx mcporter call --stdio "xcodebuildmcp" launch_app_device bundleId="com.example.MyApp"

bash

bunx mcporter call --stdio "xcodebuildmcp" launch_app_device bundleId="com.example.MyApp"

Stop App on Device

在设备上停止应用

bash

bunx mcporter call --stdio "xcodebuildmcp" stop_app_device processId=12345

bash

bunx mcporter call --stdio "xcodebuildmcp" stop_app_device processId=12345

Device Log Capture

设备日志捕获

bash

undefined

bash

undefined

Start

开始

bunx mcporter call --stdio "xcodebuildmcp" start_device_log_cap bundleId="com.example.MyApp"

Stop

停止

bunx mcporter call --stdio "xcodebuildmcp" stop_device_log_cap logSessionId="SESSION_ID"

undefined

bunx mcporter call --stdio "xcodebuildmcp" stop_device_log_cap logSessionId="SESSION_ID"

undefined

macOS Tools

macOS工具

Build macOS App

构建macOS应用

bash

bunx mcporter call --stdio "xcodebuildmcp" build_macos

bash

bunx mcporter call --stdio "xcodebuildmcp" build_macos

Build and Run macOS App

构建并运行macOS应用

bash

bunx mcporter call --stdio "xcodebuildmcp" build_run_macos

bash

bunx mcporter call --stdio "xcodebuildmcp" build_run_macos

Test macOS App

测试macOS应用

bash

bunx mcporter call --stdio "xcodebuildmcp" test_macos

bash

bunx mcporter call --stdio "xcodebuildmcp" test_macos

Get macOS App Path

获取macOS应用路径

bash

bunx mcporter call --stdio "xcodebuildmcp" get_mac_app_path

bash

bunx mcporter call --stdio "xcodebuildmcp" get_mac_app_path

Launch macOS App

启动macOS应用

bash

bunx mcporter call --stdio "xcodebuildmcp" launch_mac_app appPath="/path/to/App.app"

bash

bunx mcporter call --stdio "xcodebuildmcp" launch_mac_app appPath="/path/to/App.app"

Stop macOS App

停止macOS应用

bash

bunx mcporter call --stdio "xcodebuildmcp" stop_mac_app appName="MyApp"

bash

bunx mcporter call --stdio "xcodebuildmcp" stop_mac_app appName="MyApp"

Swift Package Tools

Swift包工具

Build Package

构建包

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_build packagePath="$(pwd)"

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_build packagePath="$(pwd)"

Test Package

测试包

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_test packagePath="$(pwd)"

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_test packagePath="$(pwd)"

Run Package Executable

运行包可执行文件

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_run packagePath="$(pwd)"

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_run packagePath="$(pwd)"

Clean Package

清理包

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_clean packagePath="$(pwd)"

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_clean packagePath="$(pwd)"

List Running Packages

列出运行中的包

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_list

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_list

Stop Package Process

停止包进程

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_stop pid=12345

bash

bunx mcporter call --stdio "xcodebuildmcp" swift_package_stop pid=12345

Project Scaffolding

项目搭建

Create New iOS Project

创建新iOS项目

bash

bunx mcporter call --stdio "xcodebuildmcp" scaffold_ios_project \
  projectName="MyApp" \
  outputPath="$(pwd)" \
  bundleIdentifier="com.example.myapp"

bash

bunx mcporter call --stdio "xcodebuildmcp" scaffold_ios_project \
  projectName="MyApp" \
  outputPath="$(pwd)" \
  bundleIdentifier="com.example.myapp"

Create New macOS Project

创建新macOS项目

bash

bunx mcporter call --stdio "xcodebuildmcp" scaffold_macos_project \
  projectName="MyMacApp" \
  outputPath="$(pwd)" \
  bundleIdentifier="com.example.mymacapp"

bash

bunx mcporter call --stdio "xcodebuildmcp" scaffold_macos_project \
  projectName="MyMacApp" \
  outputPath="$(pwd)" \
  bundleIdentifier="com.example.mymacapp"

Utility Tools

实用工具

Clean Build

清理构建

bash

bunx mcporter call --stdio "xcodebuildmcp" clean

bash

bunx mcporter call --stdio "xcodebuildmcp" clean

Show Build Settings

显示构建设置

bash

bunx mcporter call --stdio "xcodebuildmcp" show_build_settings

bash

bunx mcporter call --stdio "xcodebuildmcp" show_build_settings

Get Bundle ID from App

从应用获取Bundle ID

bash

bunx mcporter call --stdio "xcodebuildmcp" get_app_bundle_id appPath="/path/to/App.app"

bash

bunx mcporter call --stdio "xcodebuildmcp" get_app_bundle_id appPath="/path/to/App.app"

Typical Workflows

典型工作流程

Build and Test iOS App on Simulator

在模拟器上构建并测试iOS应用

bash

undefined

bash

undefined

1. Discover projects

1. 发现项目

bunx mcporter call --stdio "xcodebuildmcp" discover_projs workspaceRoot="$(pwd)"

2. List simulators

2. 列出模拟器

bunx mcporter call --stdio "xcodebuildmcp" list_sims

3. Set session defaults

3. 设置会话默认值

bunx mcporter call --stdio "xcodebuildmcp" session-set-defaults
projectPath="$(pwd)/MyApp.xcodeproj"
scheme="MyApp"
simulatorName="iPhone 16"

4. Build and run

4. 构建并运行

bunx mcporter call --stdio "xcodebuildmcp" build_run_sim

5. Run tests

5. 运行测试

bunx mcporter call --stdio "xcodebuildmcp" test_sim

undefined

bunx mcporter call --stdio "xcodebuildmcp" test_sim

undefined

UI Testing Flow

UI测试流程

bash

undefined

bash

undefined

1. Build and launch app

1. 构建并启动应用

bunx mcporter call --stdio "xcodebuildmcp" build_run_sim

2. Get UI hierarchy (ALWAYS do this before interacting)

2. 获取UI层级（交互前务必执行此操作）

bunx mcporter call --stdio "xcodebuildmcp" describe_ui

3. Take screenshot for visual reference

3. 截图作为视觉参考

bunx mcporter call --stdio "xcodebuildmcp" screenshot

4. Interact with elements using coordinates from describe_ui

4. 使用describe_ui获取的坐标与元素交互

bunx mcporter call --stdio "xcodebuildmcp" tap x=187 y=423

5. Type text

5. 输入文本

bunx mcporter call --stdio "xcodebuildmcp" type_text text="test@example.com"

undefined

bunx mcporter call --stdio "xcodebuildmcp" type_text text="test@example.com"

undefined

Error Handling

错误处理

Error	Cause	Solution
No project/workspace set	Session defaults not configured	Run `session-set-defaults` first
Simulator not found	Invalid simulator name	Run `list_sims` to get valid names
Build failed	Code errors or config issues	Check build output, run `doctor`
App not installed	Build didn't complete	Run `build_sim` before `launch_app_sim`

错误	原因	解决方案
未设置项目/工作区	未配置会话默认值	首先运行 `session-set-defaults`
未找到模拟器	模拟器名称无效	运行 `list_sims` 获取有效名称
构建失败	代码错误或配置问题	检查构建输出，运行 `doctor`
应用未安装	构建未完成	在 `launch_app_sim` 之前运行 `build_sim`

Tips

提示

Always set session defaults first - Most tools require project/scheme/simulator to be set
Use describe_ui before UI interactions - Never guess coordinates from screenshots
Check doctor for environment issues - Run
```
doctor
```
if tools aren't working
Use preferXcodebuild=true if incremental builds fail - Falls back to standard xcodebuild

始终首先设置会话默认值 - 大多数工具需要设置项目/Scheme/模拟器
在UI交互前使用describe_ui - 不要通过截图猜测坐标
使用doctor检查环境问题 - 如果工具无法工作，运行
```
doctor
```
如果增量构建失败，使用preferXcodebuild=true - 回退到标准xcodebuild