Xcode MCP Server

面向 Apple 生态系统的 Model Context Protocol 服务器

将 OpenCode、Codex 和 Claude Code 连接到 Xcode — 43 个专业工具，全部集中在单个 index.js 中

🌐 语言： English | Español

安装 • 工具 • OpenCode • Codex • Claude Code • 文档

这是什么？

Xcode MCP Server 是连接你的 AI IDE（OpenCode / Codex / Claude Code）与 Xcode + Apple 开发工具的可靠、生产就绪桥梁。

LLM 不再仅仅编写 Swift：它还能构建、测试、性能分析、管理模拟器、物理设备、签名，甚至能在精确行号处打开 Xcode — 全部通过 MCP stdio 完成，无需 HTTP 服务器。

技术栈： ES Modules · @modelcontextprotocol/sdk@1.30 · StdioServerTransport · promisify(exec) · Yarn 4 Berry · Make

• ✅ 单文件 index.js（2250 行） — 无需构建步骤、无需编译，可在单个文件中审计。Shebang #!/usr/bin/env node，可直接用于 node、yarn start 或 npx。

• ✅ 43 个工具，具有严格的 JSON Schema（additionalProperties:false）+ 全局 try/catch。每个工具返回 content: [{type:"text"}]，失败时返回 isError:true — 没有 // TODO。

• ✅ 完整的 Apple 覆盖： xcodebuild、simctl（9）、devicectl（2）、xctrace（5 个模板）、agvtool、security、osascript/xed。

• ✅ 现代开发者体验： 内置 Yarn 4（.yarn/releases）、带 help 的自文档 Makefile、模块化 docs/、macOS CI + make test 冒烟测试。

• ✅ 多客户端： 同一个 index.js 无需修改即可与 OpenCode、Codex 和 Claude Code 配合使用。

Related MCP server: Xcode MCP Server

✨ 功能特性

📋 目录

1. 环境要求

2. 逐步安装

3. 验证

4. 与 OpenCode / Codex / Claude Code 一起使用

5. 工具（43）

6. Make 命令

7. 文档

8. 架构

9. 贡献

📦 环境要求

Linux/Windows： 只有 make lint 可用（没有 Xcode）。CI 会为此运行 syntax-linux 任务。

🚀 逐步安装

请严格按照此顺序操作。逐块复制粘贴。

步骤 0 — 验证 Xcode 和 Node

xcodebuild -version
# Xcode 15.4  Build version 15F31d

node --version
# v20.11.0 (or newer)

yarn --version
# 4.18.0 — if "command not found", run:
corepack enable
corepack prepare yarn@stable --activate
yarn --version

步骤 1 — 克隆仓库

git clone https://github.com/YanxReal/Xcode-MPC.git
cd Xcode-MPC

步骤 2 — 安装依赖

选项 A — 使用 Make（推荐，现代化）：

make install

make install 会做什么：

1. 检测 yarn，如果缺失则通过 corepack 安装

2. 运行 yarn install（读取 yarn.lock，安装 @modelcontextprotocol/sdk）

3. 运行 chmod +x index.js

预期输出：

➤ YN0000: · Yarn 4.18.0
➤ YN0000: ┌ Resolution step
➤ YN0000: └ Completed
➤ YN0000: · Done with warnings in 3s
✓ dependencies installed

选项 B — 直接使用 Yarn：

yarn install
chmod +x index.js

如果你从 npm 迁移过来：

rm -f package-lock.json
yarn install

步骤 3 — 验证环境

make doctor

应显示：

Node: v20.x
Yarn: 4.18.0
Xcode: Xcode 15.x
xcrun: xcrun version 70
...
✓ doctor complete

如果你看到 xcodebuild: command not found：

sudo xcode-select -s /Applications/Xcode.app

步骤 4 — 验证 MCP 服务器

make lint
# ➜ node --check index.js
# ✓ lint ok

make test
# ➜ smoke test MCP...
# ✓ tools/list: 43 tools
# ✓ xcode_sync_strings OK
# ✓ xcode_certificates_check OK
# ✓ smoke test PASSED

或者手动：

python3 scripts/smoke_test.py
# or
node scripts/smoke_test.mjs

步骤 5 — 配置你的 AI 客户端

选择一个（或全部三个 — 同一个 index.js 随处可用）：

完整的分步指南，包含可直接复制粘贴的 JSON/TOML：

• 📘 OpenCode → docs/opencode.md

• 📗 Codex → docs/codex.md

• 📙 Claude Code → docs/claude-code.md

步骤 6 — 重启并测试

重启 OpenCode / Codex / Claude Code 并输入：

list the xcode tools

你应该会看到 43 个工具，并且在日志中看到：

✅ Xcode MCP Server started (stdio) — 43 tools registered

完成！现在你可以说：

Build MyApp with xcode_build scheme MyApp destination "platform=iOS Simulator,name=iPhone 15"

✅ 验证

# 1. Syntax
make lint

# 2. Smoke MCP (no Xcode needed, just Node)
make test

# 3. Apple environment
make doctor
# Checks: node, yarn, xcodebuild, xcrun, simctl, swiftlint, security, osascript

# 4. Visual inspector (optional)
make inspect
# or
yarn inspect
# Open http://localhost:6274 → tools/list → tools/call

🔧 与 OpenCode / Codex / Claude Code 一起使用

OpenCode

~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/Users/YanxReal/Dev/Tools/Xcode-MPC/index.js"],
      "env": {}
    }
  }
}

Codex (OpenAI)

~/.codex/config.toml:

[mcp_servers.xcode]
command = "node"
args = ["/Users/YanxReal/Dev/Tools/Xcode-MPC/index.js"]

Claude Code (Anthropic)

claude mcp add xcode -- node /Users/YanxReal/Dev/Tools/Xcode-MPC/index.js
# verify
claude mcp list
# xcode: connected — 43 tools

或者针对单个项目使用 .mcp.json：

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/Users/YanxReal/Dev/Tools/Xcode-MPC/index.js"]
    }
  }
}

每个客户端的提示词示例 → docs/opencode.md · docs/codex.md · docs/claude-code.md · 模板：.mcp.json.example · .codex-config.toml.example

🛠️ 工具（43）

1. 构建、诊断与清理

2. 测试与覆盖率

3. 模拟器 xcrun simctl (9)

simctl_list (过滤 booted), simctl_lifecycle (boot|shutdown|erase), simctl_install_launch, simctl_media_capture (screenshot|record), simctl_push_notification, simctl_location_mock, simctl_privacy_control, simctl_ui_appearance (light|dark), simctl_open_url

4. 物理设备 xcrun devicectl (2)

devicectl_list (--json), devicectl_logs (deviceUdid*, durationSeconds)

5. 性能分析 xcrun xctrace (1)

xctrace_profile (template: Time Profiler|Allocations|Leaks|System Trace, timeLimitSeconds, outputFilePath*)

6. 版本与安全 (2)

agvtool_version_bump (bump_build|set_version|set_build), xcode_certificates_check (security find-identity)

7. Xcode GUI 编辑器 (2)

xcode_get_active_file (AppleScript osascript), xcode_open_at_line (filePath*, line*, column — xed → xcode://)

8. 本地化 (1)

xcode_sync_strings (.xcstrings → missing / pendingTranslation / emptyValues)

9. 资源 Assets.xcassets + actool (6)

asset_list_contents (列出 *.colorset/*.imageset), asset_manage_color (#RRGGBB 浅色 + 深色), asset_manage_image (缩放/矢量 + preserves-vector-representation), asset_read_info (Contents.json), asset_delete (安全删除), asset_validate_actool (xcrun actool --compile)

10. AppIcon 所有 Apple 操作系统 (1)

asset_generate_appicon (iOS, macOS, watchOS, tvOS, visionOS — 42 个槽位, 若提供 baseImagePath 则使用 sips -z)

11. 包管理 SPM / CocoaPods / Carthage (11)

package_resolve/update/list/read_resolved/reset_cache/compute_checksum, spm_add/remove_dependency, cocoapods_manage, carthage_manage, cocoapods_to_spm_migrate (Podfile→Package.swift)

完整参考：JSON Schema + 可直接复制的示例 → docs/tools.md

📖 Make 命令

make help          # Show this pretty help (colors)
make install       # yarn install + chmod +x
make reinstall     # clean + install (from scratch)
make lint          # node --check index.js
make doctor        # Check Node/Yarn/Xcode/simctl/swiftlint/osascript
make test          # Smoke test MCP (43 tools + 2 calls)
make start         # yarn start (stdio)
make dev           # yarn dev (--watch)
make inspect       # MCP Inspector at http://localhost:6274
make clean         # Remove node_modules/.yarn/cache/build
make fmt           # prettier if available
make release VERSION=1.0.1  # bump + tag + push

详情 → docs/development.md

📚 文档

🧪 手动冒烟测试

# Without Make:
python3 scripts/smoke_test.py
# STDERR: ✅ Xcode MCP Server started — 43 tools
# ✓ tools/list: 43 tools
# ✓ xcode_sync_strings OK
# ✓ smoke test PASSED

# With Make:
make test

🏗️ 架构

index.js (2250 lines, 1 file)
├── Shebang + Imports (MCP SDK, promisify(exec), fs, path, os)
├── Helpers: shellEscape, expandTilde, runCommand (try/catch + 10MB buffer), formatResult
├── TOOLS[43]: Strict JSON Schema (additionalProperties:false)
├── Handlers[43]: async handle_* with validation + fallbacks (xed→xcode://, swift-format→swiftlint)
├── Dispatcher: HANDLERS map + ListTools/CallTool (try/catch → isError:true)
└── Server: StdioServerTransport (stdin JSON-RPC, stdout JSON-RPC, stderr logs)

关于单文件决策以及 OpenCode → stdin → handler → xcrun → stdout 流程，请参阅 docs/architecture.md。

🤝 贡献指南

# 1. Fork and branch
git checkout -b feat/my-tool

# 2. Develop: add to TOOLS + Handler + HANDLERS in index.js
make install && make lint && make test

# 3. Document in docs/tools.md + README.md

# 4. PR

问题反馈：Bug 报告 · 功能请求 · PR 模板

CI 在 macos-14 和 ubuntu-latest 上运行 — 你的 PR 会自动进行测试。

📄 许可证

MIT © YanxReal — 参见 LICENSE。

🔗 链接

• 仓库： https://github.com/YanxReal/Xcode-MPC

• MCP 规范： https://modelcontextprotocol.io

• SDK： https://github.com/modelcontextprotocol/typescript-sdk

• Yarn Berry： https://yarnpkg.com/getting-started

• Xcode： https://developer.apple.com/xcode/

用 ❤️ 为 Apple 生态打造 · Yarn 4 + Make + CI + Docs

如果它对你有帮助，请在 GitHub 上留下一个 ⭐