xcforge - iOS MCP Server & CLI

xcforge

用于 iOS 开发的 MCP 服务和 CLI，可通过任意 AI Agent 或终端进行构建、测试、自动化和诊断。

104 个 MCP 工具。19 组 CLI 命令。单个原生二进制文件（剥离调试符号后约 8 MB，含调试符号约 18 MB）。零外部运行时依赖。

---

安装

Homebrew（推荐）

brew tap justinthevoid/tap && brew install xcforge

Claude Code（一行命令）

claude mcp add xcforge -- xcforge

这会将 xcforge 注册为当前项目中的 MCP 服务。请先通过 Homebrew 安装，再运行此命令。

从源代码安装

git clone https://github.com/justinthevoid/xcforge.git
cd xcforge && swift build -c release
cp .build/release/XCForgeCLI /usr/local/bin/xcforge

卸载

Homebrew

brew uninstall xcforge
brew untap justinthevoid/tap   # optional: remove the tap

从源代码安装

rm /usr/local/bin/xcforge

移除 MCP 配置

卸载二进制文件后，请从 MCP 客户端配置文件中移除 "xcforge" 条目（文件位置请参见配置）。

对于 Claude Code：

claude mcp remove xcforge

---

配置

将 xcforge 添加到 MCP 客户端。不同客户端的配置格式和文件位置各不相同。

Claude Code

最快捷的方法是使用上文安装中所示的 CLI 命令。若要手动配置，请在项目根目录的 .mcp.json 中添加配置（若要全局配置，则添加到 ~/.claude/.mcp.json）：

{
  "mcpServers": {
    "xcforge": {
      "command": "xcforge",
      "args": [],
      "type": "stdio"
    }
  }
}

Claude Desktop

文件：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "xcforge": {
      "command": "/opt/homebrew/bin/xcforge",
      "args": []
    }
  }
}

注意： Claude Desktop 不会继承 shell 的 PATH。请使用完整的 Homebrew 路径——Apple Silicon 上为 /opt/homebrew/bin/xcforge，Intel 上为 /usr/local/bin/xcforge。

Cursor

文件：项目根目录中的 .cursor/mcp.json（若要全局配置，则为 ~/.cursor/mcp.json）

{
  "mcpServers": {
    "xcforge": {
      "command": "/opt/homebrew/bin/xcforge",
      "args": []
    }
  }
}

注意： 与 Claude Desktop 一样，PATH 也有此限制——请使用绝对路径。更改后请重启 Cursor。

VS Code（GitHub Copilot）

文件：项目根目录中的 .vscode/mcp.json

{
  "servers": {
    "xcforge": {
      "command": "xcforge",
      "args": [],
      "type": "stdio"
    }
  }
}

注意： VS Code 使用 "servers"，而非 "mcpServers"。需要启用 Agent 模式的 GitHub Copilot 扩展。VS Code 通常会从 shell 中解析 PATH，因此可以直接使用命令名称。

Windsurf

文件：~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "xcforge": {
      "command": "/opt/homebrew/bin/xcforge",
      "args": []
    }
  }
}

注意： 建议使用完整路径。编辑后请重启 Windsurf。

Zed

文件：~/.config/zed/settings.json（或针对单个项目使用 .zed/settings.json）

{
  "context_servers": {
    "xcforge": {
      "command": {
        "path": "/opt/homebrew/bin/xcforge",
        "args": []
      },
      "settings": {}
    }
  }
}

注意： Zed 使用 "context_servers"，并在其中嵌套 "command.path"——这与其他所有客户端都不同。

配置速查

客户端	配置键	文件位置	需要绝对路径？
Claude Code	mcpServers	.mcp.json	否
Claude Desktop	mcpServers	~/Library/Application Support/Claude/claude_desktop_config.json	是
Cursor	mcpServers	.cursor/mcp.json	是
VS Code	servers	.vscode/mcp.json	否
Windsurf	mcpServers	~/.codeium/windsurf/mcp_config.json	是
Zed	context_servers	~/.config/zed/settings.json	是

---

Claude Code 技能

xcforge 附带一项 Agent 技能：Agent 执行 iOS 任务时加载的工具参考。它包含在二进制文件中，因此安装时无需其他操作：

xcforge skill install            # this repo: .claude/skills/xcforge (commit it to share with the team)
xcforge skill install --global   # every project: ~/.claude/skills/xcforge
xcforge skill install --dir <skills-dir>      # any other agent's skills directory
xcforge skill status             # where it's installed and whether it matches this xcforge
xcforge skill show references/test-tools.md   # print one file without installing

升级 xcforge 后，重新运行 xcforge skill install 以更新副本；只有变更过的文件会被重写。除非传入 --force，否则它不会覆盖并非由它创建的 xcforge 技能目录。xcforge skill uninstall 会将其移除。

安装后，使用 xcforge 工具时，Claude 会自动加载相应的参考文件，其中包含各类别（构建、测试、模拟器、UI 自动化、日志、LLDB、诊断等）的确切参数、返回值和用法模式。

---

两种模式，同一套工具

xcforge                          # MCP server (stdio JSON-RPC, 104 tools)
xcforge build --scheme MyApp     # CLI mode (19 command groups)

通过 MCP 提供的每种工具都有对应的 CLI 命令。每个 CLI 命令都支持 --json。

---

工具概览

类别	数量	亮点
构建	6	build_sim、build_compile（仅快速编译）、build_run_sim、clean、项目/方案发现
测试	7	test_sim（含 xcresult 解析）、test_failures、test_coverage、list_tests、test_plan_inspect、Agent 输出模式、已知失败门控
模拟器	18	完整生命周期 + 视频录制、位置模拟、深色模式切换、状态栏覆盖、信息
实体设备	10	通过 devicectl 实现 — 列出、安装、启动（深层链接、环境变量）、截屏、在设备上运行 WebDriverAgent
UI 自动化	20	WebDriverAgent + 原生 AX 桥接 — 查找、点击（点或像素）、滑动、拖动、输入、处理提醒
屏幕截图	3	帧缓冲区捕获（0.3s）、点空间坐标对齐、可选网格叠加
视觉回归	3	像素差异基线、多设备检查（深色模式、横屏、iPad）、bless 工作流
日志	4	4 层过滤捕获、8 个主题类别、正则表达式等待
控制台	3	捕获已启动应用的 stdout/stderr
SPM	5	解析、更新、显示依赖项、重置、清理
辅助功能	5	审核标签、特征、VoiceOver 顺序、对比度
Git	5	状态、差异、日志、提交、分支
LLDB 调试器	8	附加、断点、检查变量、回溯、单步/继续、任意命令
诊断	10	多步骤工作流：构建、运行、检查、捕获证据、比较、验证
计划执行	2	带断言的脚本化多步骤自动化
会话	3	持久化默认设置、.xcforge.yaml 仓库配置、会话配置文件

---

主要功能

结构化测试结果

测试输出从 .xcresult 包中解析——这是 Xcode 内部生成的结构化格式——而非从原始 xcodebuild stdout/stderr 中解析。

一次 test_sim 调用即可返回：通过/失败数量、包含源代码位置的失败消息、导出的失败截图，以及 xcresult 路径，供通过 test_failures 或 test_coverage 进一步检查。

快速截图

screenshot 工具通过 CoreSimulator 的 IOSurface API 读取模拟器帧缓冲区；如果不可用，则依次回退到 ScreenCaptureKit 和 simctl。典型延迟约为 300ms。

无需 Appium 的 UI 自动化

xcforge 通过 HTTP 直接与 WebDriverAgent 通信，并使用原生辅助功能 API 桥接（AXPBridge）作为补充。这意味着：

• find_element 配合 scroll: true 时，会使用 3 种备用策略自动滚动
• handle_alert 会搜索 SpringBoard、ContactsUI 和当前活动应用 — 一次调用 accept_all 即可清除多个权限对话框
• drag_and_drop 支持使用元素 ID，而不只是坐标
• get_source 可在约 20ms 内返回完整视图层级

按主题筛选日志

start_log_capture 会通过 4 层过滤器流式传输 os_log：

1. 排除噪声 — 在流级别剔除 15 个已知的高噪声进程
2. 捕获模式 — smart（范围广，可按主题筛选）、app（范围窄，自动检测 bundle）、verbose
3. 主题筛选 — read_logs 将日志行归类为 8 个主题（app、崩溃、网络、生命周期、springboard、widgets、后台、系统），默认仅显示 app + 崩溃
4. 去重 — 合并重复行

响应中会包含带数量的主题菜单，因此 Agent 可以按需拉取特定主题，无需重新查询。

交互式 LLDB 调试器

提供 8 个工具，可将 LLDB 附加到正在运行的模拟器进程、设置断点、检查变量、查看堆栈跟踪并单步执行代码。会话会保留 30 分钟，因此可以只附加一次，然后执行多项调试操作。CLI 命令为一次性操作（附加 → 操作 → 分离）。包括：

• 会话管理：lldb_attach（按 bundle ID 或 PID 附加）、lldb_detach
• 断点：按文件 + 行号或函数名设置，按 ID 移除
• 检查：在当前栈帧中计算表达式、查看堆栈跟踪
• 执行控制：继续、单步跳过、单步进入、单步跳出（超时为 10 秒）
• 原始透传：运行任意 LLDB 命令

可结合日志和屏幕截图进行系统化根因分析。

诊断工作流

提供 10 个工具（默认关闭：使用 XCFORGE_TOOL_GROUPS=+diagnose 或 tool_groups 启用），可串联成结构化诊断流程——启动会话、构建、启动应用、捕获运行时信号、收集证据（屏幕截图、日志、无障碍状态）、与之前的运行进行比较，并验证修复效果。专为 Agent 设计，可在多轮迭代中系统地调试问题。

物理设备支持

封装 Apple devicectl 的工具，可用于真实设备：列出已连接设备、安装、启动（支持深度链接和环境变量）和终止应用，以及截取屏幕截图。xcforge wda start --device <udid> --team <TEAM>（MCP wda_start）会在设备上构建、签名并启动 WebDriverAgent，以便 UI 自动化工具也能在设备上运行；详见 device-tools.md。

---

CLI 示例

xcforge init                                     # Scaffold a committed .xcforge.yaml (repo defaults)
xcforge build                                    # Build (auto-detects project, scheme, sim)
xcforge build compile --scheme MyApp             # Fast compile-only check (~5s)
xcforge build --scheme MyApp --simulator "iPhone 16 Pro"
xcforge test --scheme MyApp --json               # Run tests, JSON output
xcforge test --for agent                         # Agent-optimized slim JSON
xcforge test --gate                              # Subtract known-failures.yaml
xcforge test rerun-failed                        # Replay last run's failures
xcforge test plan inspect --plan AllTests        # Inspect .xctestplan
xcforge build-test --env BLESS_BASELINE=1        # Inject env var into test process
xcforge test failures --xcresult /path/to.xcresult
xcforge test coverage --min-coverage 80
xcforge bless --baseline login --tests "UITests/LoginTests"  # Baseline+test+diff in one call
xcforge sim list                                 # List simulators
xcforge sim boot "iPhone 16 Pro"
xcforge sim info                                 # Booted simulator screen size and scale
xcforge ui find --aid "loginButton"              # Find by accessibility ID
xcforge ui tap --element el-0                    # Tap element at point coordinates
xcforge ui tap-pixel --x 750 --y 1334            # Tap at pixel coordinates
xcforge screenshot                               # Screenshot to stdout
xcforge screenshot --grid --output /tmp/x.png    # Screenshot with point-coordinate grid
xcforge pose Settings                            # Build, install, launch to a screen
xcforge log start                                # Start log capture
xcforge log read --include network               # Read with topic filter
xcforge spm resolve                              # Resolve packages
xcforge device list                              # Connected physical devices
xcforge debug attach --bundle-id com.example.App    # Attach debugger
xcforge debug breakpoint set --bundle-id com.example.App --file ViewController.swift --line 42
xcforge debug inspect --bundle-id com.example.App --expression "self.count"
xcforge debug backtrace --bundle-id com.example.App # Show stack trace
xcforge debug continue --bundle-id com.example.App --mode step-over
xcforge diagnose start --scheme MyApp            # Start diagnosis session

---

替代方案

以下是一些值得了解的 iOS 专用 MCP 服务：

服务	Stars	范围	构建	测试	UI 自动化	屏幕截图	视觉回归	无障碍功能	实体设备	SPM	Git	日志
xcforge	—	104 个工具	是	是	是	是	是	是	是	是	是	是
XcodeBuildMCP	~5k	~15 个工具	是	是	部分	否	否	否	否	否	否	否
ios-simulator-mcp	~1.8k	~10 个工具	否	否	是	是	否	否	否	否	否	否
xcode-mcp-server	~370	~8 个工具	部分	否	否	否	否	否	否	否	否	否
iosef	<10	~5 个工具	否	否	是	否	否	否	否	否	否	否
Appium MCP	<50	~10 个工具	否	否	是	是	否	否	部分	否	否	否

• XcodeBuildMCP — 最受欢迎的 iOS MCP 服务，由 Sentry 支持。全面涵盖构建、测试和模拟器管理。如果你只需要构建／运行工作流，这是个可靠的选择。
• ios-simulator-mcp — 专注于模拟器 UI 交互，包括屏幕截图、点按、滑动和无障碍树。如果你只需要模拟器自动化，这是个不错的选择。
• xcode-mcp-server — 早期的 Xcode 项目管理 MCP 服务。集成能力基础，不支持模拟器自动化、测试或设备。
• iosef — 针对 Agent 优化的模拟器 CLI，使用体验简洁顺畅。范围有限，但设计周到。原生 Swift。
• Appium MCP — 通过 Appium 生态系统实现跨平台支持（iOS + Android）。需要 Node.js + Java + Appium 服务，依赖链较重。

xcforge 的定位： 它将快速编译检查、构建、测试、像素级精准的 UI 自动化、屏幕截图网格、按屏幕定位启动、日志分析、视觉回归、设备支持、SPM、无障碍审计和多步骤诊断整合到一个零依赖二进制文件中。其取舍是仅支持 iOS，不支持 Android、watchOS 或 visionOS。

---

UI 自动化设置

UI 自动化工具需要在模拟器上运行 WebDriverAgent（WDA）后端。xcforge 会自动管理 WDA 连接，你只需指定一个 WDA 项目即可。

xcforge 会按顺序尝试两个后端：

1. xcforgeWDA（首选）— xcforge 自己的 WDA 分支（com.xcforge.wda.runner）。设置 XCFORGE_WDA_DIR 后会自动构建并部署。
2. 原版 WebDriverAgent（回退方案）— Facebook/Appium 的 WDA。如果 WDA 已在端口 8100 上运行，系统会自动使用它。

快速设置

克隆 appium/WebDriverAgent，将项目和 scheme 重命名为 xcforge，然后设置 XCFORGE_WDA_DIR：

git clone https://github.com/appium/WebDriverAgent.git xcforgeWDA

# Copy project with xcforge name and remap bundle ID
cp -r xcforgeWDA/WebDriverAgent.xcodeproj xcforgeWDA/xcforgeWDA.xcodeproj
sed -i '' 's/com\.facebook\.WebDriverAgentRunner/com.xcforge.wda.runner/g' \
  xcforgeWDA/xcforgeWDA.xcodeproj/project.pbxproj

# Add xcforgeWDARunner scheme
cp xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/WebDriverAgentRunner.xcscheme \
   xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/xcforgeWDARunner.xcscheme
sed -i '' 's/WebDriverAgent\.xcodeproj/xcforgeWDA.xcodeproj/g' \
  xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/xcforgeWDARunner.xcscheme

然后将 XCFORGE_WDA_DIR 添加到 MCP 配置中：

{
  "mcpServers": {
    "xcforge": {
      "command": "xcforge",
      "env": {
        "XCFORGE_WDA_DIR": "/path/to/xcforgeWDA"
      }
    }
  }
}

xcforge 会在首次调用模拟器上的 UI 工具时自动构建并部署 WDA（首次运行约需 30–60 秒，之后可即时完成）。对于实体设备，先运行 xcforge wda start --device <udid> --team <TEAM>（MCP wda_start），并确保设备已解锁，且已在“设置”>“开发者”中开启“启用 UI 自动化”。有关其他配置、自定义端口和故障排除，请参阅完整的 UI 自动化设置指南。

---

要求

• macOS 13+
• Xcode 15+
• Swift 6.0+（仅源码构建需要）
• WebDriverAgent（仅用于 UI 自动化 — 参见 UI 自动化设置）

---

Web 基线（Story 1.1）

Web 工作区隔离在 Web/ 下，使用 Astro Starlight 和 Svelte，并且仅使用 Bun 管理软件包和脚本，仅使用 Biome 进行 lint 和格式检查。

cd Web
bun install
bun run typecheck
bun run lint
bun run validate

运行 bun run dev 后的本地路由：

• 营销页面路由：http://localhost:4321/
• 文档路由：http://localhost:4321/docs
• 文档深层路由：http://localhost:4321/docs/getting-started

如果设置失败，请运行：

cd Web
bun run doctor

解决步骤见 Web/README.md。

---

支持

如果 xcforge 为你节省了时间，欢迎支持开发：

许可证

MIT — 参见 LICENSE。

贡献

欢迎提交 Issue 和 PR。参见 CONTRIBUTING.md。