---

Cursor 客户端开发：XcodeBuildMCP 和 adb-mcp

Cursor 写 Swift / Kotlin 已经够用。客户端开发真正卡住的，往往不是「这段 Compose 怎么写」，而是：编完了吗、模拟器起来了吗、界面长什么样、那个按钮点下去会怎样、logcat 里有没有崩。

这两套 MCP 就是补这一截的：

• XcodeBuildMCP：给 Cursor 接上 xcodebuild / 模拟器 / 真机 / 截图 / 点按 / LLDB，面向 iOS（也覆盖 macOS）。
• adb-mcp：给 Cursor 接上 adb + Gradle + 模拟器 / 真机 / 控件树 / 点按 / logcat，面向 Android 原生（以后 KMP 的 Android 目标也能用）。

一句话：Skill / 文档 MCP 教模型怎么写；这两套让模型在真设备上把 App 跑起来看一眼。

---

1. 先记住三件事

1. 它们不替代 Xcode / Android Studio 的安装，替代的是「为了编一下、跑一下而把 IDE 窗口开一整天」。
2. 它们不写业务代码。写代码还是 Cursor；它们负责编、装、跑、截图、点、查日志。
3. 不必两个都开着。做 iOS 用 XcodeBuildMCP，做 Android 用 adb-mcp。KMP 以后也是这套：Android 目标走 adb-mcp，iOS 目标走 XcodeBuildMCP。

和「查官方文档」那类 MCP 也不一样。Google Developer Knowledge、Apple Docs、Figma 解决的是知识和设计稿；这两套解决的是本机工程闭环。

---

2. 客户端 Agent 到底缺哪一层

用 Cursor 做 Web，Agent 改完代码可以自己开浏览器看。用 Cursor 做 App，默认情况下它只能改文件，然后跟你说「请在 Xcode 里 Command + R」。

中间缺的是一层工具：

层	谁来做	例子
知识	Skill、文档 MCP	AGP 9 怎么升、Navigation 3 怎么写
改代码	Cursor 自己	改 Kotlin / Swift 文件
编、跑、看	这两套 MCP	模拟器启动、安装、截图、点登录
设计稿	Figma / MasterGo MCP	把 frame 变成布局结构

所以装完之后，比较自然的对话是：

按这个 Figma 改一版登录页，用 iPhone 16 模拟器编起来，截张图对照一下。登录按钮点下去如果还是空白，把 logcat / 控制台日志贴给我。

没有 MCP 时，后半句只能你自己切到 IDE 里做。

---

3. 和 Xcode、Android Studio 的关系

日常编译、跑模拟器、截图、点按、看日志，可以不打开两个 IDE 的窗口。

	可以不打开窗口	仍然要装	还是得打开 IDE 的时候
iOS	xcodebuild + 模拟器 + 截图 + 点按 + 测试	必须装完整 Xcode，只装 Command Line Tools 没有模拟器	SwiftUI Preview、证书/描述文件、Instruments、第一次允许 MCP 桥
Android	gradlew + adb + 模拟器 + 控件树 + logcat	必须有 Android SDK（模拟器、platform-tools）	Layout Inspector、Profiler、Studio 里的 Compose Preview、图形化断点

XcodeBuildMCP 里有一项 xcode-ide：只有 Xcode 开着 时，才能代理 Apple 自带 MCP（Preview 出图、Issue Navigator）。不做 Preview 可以当它不存在，主循环照样跑。

adb-mcp 完全不依赖 Android Studio 进程。Studio 装过一次、SDK 还在，就行。

---

4. 安装：放到一个目录里管

不要今天 npx、明天 Homebrew、后天又一份缓存。推荐本机统一目录：

~/.local/mcp/bin/xcodebuildmcp
~/.local/mcp/bin/adb-mcp

~/.local/bin 里再做符号链接，终端也能直接敲命令。

4.1 装 XcodeBuildMCP

需要：macOS、已装 Xcode（建议 16+，26.3 才能用 IDE 桥）、本机有 Node。

mkdir -p ~/.local/mcp/bin
npm install -g --prefix ~/.local/mcp xcodebuildmcp@latest
ln -sfn ~/.local/mcp/bin/xcodebuildmcp ~/.local/bin/xcodebuildmcp
xcodebuildmcp --version
xcodebuildmcp-doctor

当前稳定版本是 2.7.0 一带。doctor 会检查 Xcode 路径、模拟器 UI 自动化（axe）、LLDB。

4.2 装 adb-mcp

需要：Android SDK，adb 和 emulator 能用。SDK 常见位置：~/Library/Android/sdk。

从 GitHub Release 下对应平台的 tar.gz，核对 checksums.txt 后再放进 ~/.local/mcp/bin。不要随手 curl | sh 也行，自己下包更清楚。

# 装好后
chmod +x ~/.local/mcp/bin/adb-mcp
ln -sfn ~/.local/mcp/bin/adb-mcp ~/.local/bin/adb-mcp
adb-mcp -version

当前版本 0.23.0。如果 shell 里没有 ANDROID_HOME，务必在 Cursor 的 MCP 配置里写上 SDK 路径，否则 Agent 找不到模拟器。

4.3 更新

npm install -g --prefix ~/.local/mcp xcodebuildmcp@latest
# 或
xcodebuildmcp upgrade

adb-mcp update

---

5. 接到 Cursor

全局配置：~/.cursor/mcp.json。用绝对路径，不要写 npx -y ...@latest，否则每次启动都去抢缓存。

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "/Users/你的用户名/.local/mcp/bin/xcodebuildmcp",
      "args": ["mcp"],
      "env": {
        "XCODEBUILDMCP_CWD": "${workspaceFolder}",
        "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,simulator-management,project-discovery,ui-automation,debugging,device,xcode-ide,utilities,doctor,workflow-discovery",
        "PATH": "/Users/你的用户名/.local/mcp/bin:/Users/你的用户名/.local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    },
    "adb-mcp": {
      "command": "/Users/你的用户名/.local/mcp/bin/adb-mcp",
      "env": {
        "ANDROID_HOME": "/Users/你的用户名/Library/Android/sdk",
        "ANDROID_SDK_ROOT": "/Users/你的用户名/Library/Android/sdk",
        "PATH": "/Users/你的用户名/Library/Android/sdk/platform-tools:/Users/你的用户名/Library/Android/sdk/emulator:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}

保存后打开 Cursor：Settings → Tools & MCP，两个名字旁边应该是绿点。

关于 XCODEBUILDMCP_ENABLED_WORKFLOWS：默认只开 simulator，工具少、省上下文，但点按、真机、LLDB 都没有。上面这份是「客户端日常够用」的组合。macOS 桌面 App、Swift Package 独立工程如果也要，再把 macos、swift-package 加进去。

XcodeBuildMCP 还带一个 Agent Skill。装到 Cursor 用户 Skill 目录后，Agent 会优先走 build-and-run，而不是自己拼一长串 xcodebuild：

xcodebuildmcp init --skill mcp --client agents --dest ~/.cursor/skills --force

---

6. XcodeBuildMCP 能干什么

面向 Apple 平台。CLI 和 MCP 是同一套工具，终端里也可以 xcodebuildmcp simulator build-and-run ...。

6.1 工程

• 扫描目录，找出 .xcodeproj / .xcworkspace
• 列出 scheme
• 查看 build settings
• 从 .app 里取出 bundle id

第一次在某个仓库里用，Agent 通常会先 discover-projects 再 session_set_defaults，把工程路径、scheme、模拟器名字记下来。后面就不用每次重复参数。

6.2 模拟器（日常主路径）

• 列出、启动、打开模拟器窗口
• build：只编译
• build-and-run：编译 → 安装 → 启动，日志一并收（最常用）
• 安装已有 .app、启动、停止
• 跑测试
• 截图、录屏
• 抓一份带控件引用的 UI 快照，后面的 tap 才能对准

模拟器环境还可以：擦除、改深色模式、改定位、改状态栏网络图标、开关软键盘。适合截商店图或复现「定位权限 / 深色模式」问题。

6.3 真机

列出已连接的 iPhone / iPad，为真机编译、安装、启动、停止、跑测试。签名、证书出问题时代理解决不了图形化配置，还是要开 Xcode。

6.4 UI 自动化

在已经跑起来的模拟器 App 上：

• 截图
• 等到某个控件出现
• 点、长按、滑、拖、输入文字
• 按 Home / 音量等
• 同一屏批量操作

这是「改完 UI 对不对」的关键。没有它，Agent 只能猜布局。

6.5 调试

把 LLDB 挂到模拟器进程：下断点、继续、看堆栈、看变量、执行 LLDB 命令。替代不了 Xcode 调试器窗口的全部体验，但「崩了抓一下堆栈」够用。

6.6 Xcode IDE 桥（可选）

Xcode 26.3+ 且窗口开着时：

• 列出 Apple 自带 MCP 有哪些工具
• 代调：SwiftUI Preview 渲染图、Issue Navigator、文档搜索

Preview 仍然是 Xcode 的能力，只是 Cursor 可以远程要一张图。Cursor 对接裸 xcrun mcpbridge 有协议兼容坑，所以更建议走 XcodeBuildMCP 这一层代理，不要再单独加一份 Xcode MCP。

6.7 它不能做什么

• 不能代替装 Xcode
• 不能在模拟器里替代 TestFlight / 上架审核
• 不能凭空生成证书和描述文件
• 不负责把 Figma 变成 SwiftUI（那是 Figma MCP）
• 不理解你的业务架构，乱 scheme 一样会编失败
• Apple 自带桥的 Preview，离开 Xcode 窗口就没了

---

7. adb-mcp 能干什么

面向 Android。Agent 通过结构化工具调 adb 和 Gradle，而不是自己拼一串容易写错的 shell。

7.1 设备

• 列出 AVD，启动模拟器并等到开机
• 列出当前 adb devices
• 关机、无线配对、adb reverse（RN/Expo 偶要用，原生一般用不到）

7.2 看见界面

• screenshot：截 PNG。黑屏会重试，并标出是锁屏还是 FLAG_SECURE
• describe_ui：控件树，带文本、contentDescription、id，以及真实像素中心。点按靠这个瞄准，不要对着缩略图估坐标
• render_stats：掉帧、jank，适合「这个列表怎么这么卡」

折叠屏可以指定内外屏。

7.3 动手

• 按坐标点、按文字点、按 resource id 点
• 长按、滑、拖、输入、返回、Home、组合键
• 等到某段文字出现再点（列表可以边滑边等）
• run_sequence：多步一次做完，避免每一步都来回通信，把限时弹窗给错过了

点完可以开 verify_change：界面其实没变的话会告诉你，而不是假装成功。

7.4 锁、指纹、模拟器扩展

测 Keystore、BiometricPrompt、OTP 时有用：

• 设置 / 清除 PIN
• 模拟指纹按下和抬起（模拟器）
• 发短信、模拟来电、改电量、旋转、弱网、传感器、AVD 快照

这些是 Extended Controls 那一层，控件树里是看不见的。

7.5 App 生命周期

安装 / 卸载 / 启动 / 强停、清数据、授权、Deeplink、推拉文件、是否在前台、最近一次崩溃栈。

7.6 日志

• 一次性 logcat，可按 tag、级别、时间窗过滤，可把 token 打码
• 先 clear 再操作再读，只看这一次的日志
• 录屏

7.7 Gradle

这是它相对「纯手机自动化 MCP」最大的差别：

• 列出工程模块、variant
• assembleDebug
• 单测、仪器测试、覆盖率
• build_and_run：编完装上打开

原生应用、以后 KMP 的 :androidApp / :shared 都走这一套。它不识别 Gradle 以外的 iOS 目标，KMP 的 iOS 还是交给 XcodeBuildMCP。

7.8 它不能做什么

• 不能替代 Android SDK / 至少一个 AVD（或真机）
• 没有 Studio 的 Layout Inspector、Profiler、Compose Preview
• 不能在设备上点「系统设置里的图形界面」到任意深度（能 adb，但不是万能 UI 机器人）
• 对 Compose 无 id 的节点，优先靠文字 / contentDescription；都没有时只能截图 + 坐标
• 不负责架构和 Jetpack 最佳实践（那是 Android Skills）
• GitHub 星少、社区项目，行为以本机二进制为准，大版本记得看 changelog

---

8. 对照：同一件事两边怎么说

你想做的	跟 Cursor 怎么说（iOS）	跟 Cursor 怎么说（Android）
编起来跑	用 XcodeBuildMCP 在 iPhone 16 模拟器 build-and-run	用 adb-mcp 启动模拟器，assembleDebug 装上打开
看长什么样	截图，描述当前界面	screenshot + describe_ui
点一下验证	点「登录」，再截图	tap_on_text 登录，再截图
查崩	看控制台；必要时 LLDB 堆栈	last_crash 或 logcat 过滤包名
真机	列出设备，build-and-run 到真机	list_devices 后带上 serial

模型选择：这类任务是大量工具调用，用执行向模型（例如 Composer 2 / Fast）比用高推理模型更合适，否则钱花在「思考」而不是等编译上。

---

9. 推荐提问方式

可以和之前那篇 Developer Knowledge 一样，固定一个模板，Agent 不容易跑偏。

iOS

用 XcodeBuildMCP：
【工程】当前仓库的 iOS App
【目标】在 iPhone 16 模拟器上跑起来
【步骤】
1. 如有必要先发现工程并设置 session defaults（scheme / 模拟器）
2. build-and-run，不要只 build
3. 截图，用中文描述当前界面
4. 若编译失败，根据报错改代码再编，直到能启动
【不要】自己拼原始 xcodebuild，不要叫我去 Xcode 里点运行

改完 UI 再补一句：

截图后点「<按钮文案>」，等界面稳定再截一张，对比和 Figma 的差异。

Android

用 adb-mcp：
【工程】当前 Android 原生工程
【目标】debug 包装到模拟器并打开
【步骤】
1. list_devices，没有设备就 boot_emulator
2. 用 Gradle 编 debug 并安装启动
3. screenshot + describe_ui
4. 需要的话 tap_on_text 点「<文案>」再截图
5. 出错就 logcat 过滤本应用包名
【不要】让我去 Android Studio 里点 Run

两个一起（KMP 以后）

shared 模块改的是公共逻辑。
- Android：adb-mcp 编 :androidApp 装模拟器验证
- iOS：XcodeBuildMCP 编 iOS scheme 装模拟器验证
先做 Android，通过后再做 iOS。

---

10. 一条真实工作流（Android 举例）

假设改了登录页：

1. Cursor 改 Compose。
2. Agent 调 list_devices，没有设备就 boot_emulator。
3. build_and_run 或 assembleDebug + install_app + launch_app。
4. screenshot 看像不像。
5. describe_ui 里找到「登录」，tap_on_text。
6. 再截图。如果还停在登录页，logcat 看接口是不是 401。
7. 改代码，从第 3 步再来。

iOS 把 2–3 换成 build-and-run，把 5 换成 UI automation 的 tap，逻辑一样。

人要做的：看截图是不是你要的产品效果，以及签名 / 系统弹窗这种 MCP 处理不好的步骤。

---

11. 排错

MCP 是红点 / 0 tools

• 路径是不是绝对路径，Cursor 启动时 PATH 经常不完整
• XcodeBuildMCP 的 args 必须有 mcp
• 改完 mcp.json 要在设置里刷新 MCP

iOS 编过、装不上模拟器

• xcodebuildmcp-doctor 看 Xcode 是否被 xcode-select 指到正式版
• scheme 名字是不是 App 那个，不是 Pods
• 第一次用 xcode-ide：先开 Xcode，点若干次 Allow，再让 Agent 调 list-tools

Android 提示找不到 SDK

• ANDROID_HOME 写进 MCP 的 env，不要只写在 .zshrc 里（Cursor 子进程未必读 shell 配置）
• emulator 和 platform-tools 都要在 PATH 里
• 至少在 Device Manager 里建过一个 AVD，adb-mcp 才能 boot_emulator

点了没反应

• iOS：先 snapshot-ui / 截图，再用返回的 elementRef，不要盲点坐标
• Android：用 describe_ui 的 center；Compose 没 id 就用文字；系统弹窗可能挡住，看 top window 是不是你的 App

工具特别多、上下文爆炸

• XcodeBuildMCP 用 XCODEBUILDMCP_ENABLED_WORKFLOWS 减组
• 不必两个 MCP 同时为同一个问题服务

---

12. 什么时候不要用它们

• 只改文案、只问 API 怎么用：用文档 MCP / Skill 就行，开一次模拟器是浪费。
• 要像素级 Preview、要 Profiler 火焰图：开对应 IDE。
• 要上架：还是 EAS / Transporter / Play Console，这两套最多帮你打出包、跑测试。
• 安全：它们能装 App、清数据、读 logcat。不要对着生产账号、真短信验证码无脑授权 Agent。

---

13. 小结

	XcodeBuildMCP	adb-mcp
平台	iOS / 模拟器 / 真机（可加 macOS）	Android 模拟器 / 真机
构建	xcodebuild	Gradle
看见	截图、UI snapshot	截图、describe_ui
验证	点按、手势、LLDB	点按、logcat、指纹/短信等模拟
要开 IDE 吗	编跑不用；Preview / 签名要	编跑不用；Inspector / Profiler 要
适合谁	原生 iOS、KMP iOS 目标	原生 Android、KMP Android 目标

装好之后，客户端开发在 Cursor 里才真正形成闭环：改代码 → 跑起来 → 看见 → 再改。之前缺的不是另一个会写 Swift 的模型，是这层手和眼睛。