xcode-studio-mcp

用于 Xcode + iOS 模拟器的统一 MCP 服务器 —— 可从 Claude Code、Codex、Cursor 或任何 MCP 客户端构建、部署、截图并与您的 iOS 应用进行交互。

使用 Swift 构建。单一二进制文件。无需 Node/Python 运行时。

License: MIT Swift 6.0+ MCP

为什么存在这个项目

目前，您需要 2-3 个独立的工具才能与 AI 代理完成完整的 iOS 开发循环。xcode-studio-mcp 将它们合而为一：

Write code → Build → Deploy to Simulator → Screenshot → Tap/Type → Verify

工具

工具	描述
`xcode_build`	构建 Xcode 项目并输出结构化错误信息（文件、行、列、严重性、消息）
`xcode_run`	在 iOS 模拟器中构建并启动应用
`simulator_screenshot`	将模拟器屏幕捕获为 PNG 图像
`simulator_tap`	在模拟器屏幕的 x,y 坐标处点击
`simulator_type`	在当前聚焦的字段中输入文本
`simulator_describe`	获取当前屏幕的辅助功能树 (JSON)

工具参数

`xcode_build`

参数	必需	描述
`project_path`	是	Xcode 项目目录、`.xcodeproj` 或 `.xcworkspace` 的路径
`scheme`	否	构建方案（如果省略则自动检测）
`configuration`	否	`Debug`（默认）或 `Release`
`destination`	否	构建目标（默认为已启动的模拟器）

`xcode_run`

参数	必需	描述
`project_path`	是	Xcode 项目路径
`bundle_identifier`	是	应用 Bundle ID（例如 `com.example.MyApp`）
`scheme`	否	构建方案（自动检测）
`simulator_udid`	否	目标模拟器（默认为已启动的）

`simulator_screenshot`

参数	必需	描述
`simulator_udid`	否	目标模拟器（默认为已启动的）

`simulator_tap`

参数	必需	描述
`x`	是	X 坐标
`y`	是	Y 坐标
`duration`	否	按住时长（秒，用于长按）
`simulator_udid`	否	目标模拟器

`simulator_type`

参数	必需	描述
`text`	是	要输入的文本
`simulator_udid`	否	目标模拟器

`simulator_describe`

参数	必需	描述
`simulator_udid`	否	目标模拟器

快速入门

先决条件

安装了 Xcode 的 macOS
对于 UI 交互工具（tap、type、describe）：

brew tap facebook/fb && brew install idb-companion
pip3 install fb-idb

构建

git clone https://github.com/kevinswint/xcode-studio-mcp.git
cd xcode-studio-mcp
swift build -c release

配置 Claude Code

添加到您的 Claude Code MCP 设置中：

{
  "mcpServers": {
    "xcode-studio-mcp": {
      "command": "/path/to/xcode-studio-mcp/.build/release/XcodeStudioMCP"
    }
  }
}

示例工作流

You: Build and run my app at ~/Projects/MyApp
Claude: [calls xcode_build] Build succeeded with 0 errors
        [calls xcode_run] App launched (PID 12345)
        [calls simulator_screenshot] Here's what the app looks like...
        [calls simulator_describe] I can see a "Sign In" button and email/password fields
        [calls simulator_tap] Tapped the email field
        [calls simulator_type] Typed "test@example.com"
        [calls simulator_screenshot] Here's the current state...

架构

┌─────────────────────────────┐
│     MCP Protocol Layer      │  stdio transport (Swift MCP SDK)
├─────────────────────────────┤
│   Tool Implementations      │  6 tools, structured error output
├──────────┬──────────────────┤
│ xcodebuild│  simctl  │  idb │  native process calls
│  wrapper  │  wrapper │ CLI  │
└──────────┴──────────┴──────┘

使用 Swift 构建，零 Node/Python 运行时依赖（仅 UI 交互工具需要 idb CLI）。

路线图

v0.1（当前）：核心构建 + 模拟器工具
v1.0：语义化 UI 导航（“点击登录按钮”）、视觉差异对比、Xcode 项目文件操作、复合操作、SwiftUI 预览捕获

贡献

欢迎提交 PR。代码库约为 750 行 Swift 代码，组织为 Tools、Services 和 Models。

许可证

MIT

项目	功能	区别
XcodeBuildMCP	仅构建 + 测试	无模拟器 UI 交互
mobile-mcp	跨平台模拟器 UI	无 Xcode 构建支持
ios-simulator-mcp	通过 IDB 控制模拟器	无构建功能，所有操作依赖 IDB

Xcode-Studio-MCP