Xcode MCP Server is a serious, production-ready bridge between your AI IDE (OpenCode / Codex / Claude Code) and Xcode + Apple Dev Tools.

An LLM no longer just writes Swift: it builds, tests, profiles, manages simulators, physical devices, signing and even opens Xcode on the exact line — all via MCP stdio with no HTTP server.

Stack: ES Modules · @modelcontextprotocol/sdk@1.30 · StdioServerTransport · promisify(exec) · Yarn 4 Berry · Make

• ✅ Single-file index.js (2250 lines) — no build step, no compile, auditable in one file. Shebang #!/usr/bin/env node, ready for node, yarn start or npx.
• ✅ 52 tools with strict JSON Schema (additionalProperties:false) + global try/catch. Each tool returns content: [{type:"text"}] and isError:true on failure — no // TODO.
• ✅ Full Apple coverage: xcodebuild, simctl (9), devicectl (2), xctrace (5 templates), agvtool, security, osascript/xed.
• ✅ Modern DX: Vendored Yarn 4 (.yarn/releases), self-documenting Makefile with help, modular docs/, macOS CI + make test smoke.
• ✅ Multi-client: same index.js works with OpenCode, Codex and Claude Code without changes.

1. Requirements
2. Step-by-step Installation
3. Verification
4. Usage with OpenCode / Codex / Claude Code
5. Tools (52)
6. Make Commands
7. Documentation
8. Architecture
9. Contributing

Linux/Windows: only make lint works (no Xcode). CI runs a syntax-linux job for that.

Follow exactly in this order. Copy and paste block by block.

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

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

Option A — with Make (recommended, modern):

make install

What make install does:

1. Detects yarn, installs via corepack if missing
2. Runs yarn install (reads yarn.lock, installs @modelcontextprotocol/sdk)
3. Runs chmod +x index.js

Expected output:

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

Option B — with Yarn directly:

yarn install
chmod +x index.js

If you come from npm:

rm -f package-lock.json
yarn install

make doctor

Should show:

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

If you see xcodebuild: command not found:

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

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

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

Or manually:

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

Pick one (or all three — same index.js works everywhere):

Full step-by-step with copy-paste JSON/TOML:

• 📘 OpenCode → docs/opencode.md
• 📗 Codex → docs/codex.md
• 📙 Claude Code → docs/claude-code.md

Restart OpenCode / Codex / Claude Code and type:

list the xcode tools

You should see 52 tools and in the log:

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

Done! Now you can say:

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

~/.config/opencode/opencode.json:

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

~/.codex/config.toml:

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

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

Or per-project with .mcp.json:

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

Prompt examples for each client → docs/opencode.md · docs/codex.md · docs/claude-code.md · Templates: .mcp.json.example · .codex-config.toml.example

simctl_list (filter 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

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

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

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

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

xcode_sync_strings (.xcstrings → missing / pendingTranslation / emptyValues)

asset_list_contents (list *.colorset/*.imageset), asset_manage_color (#RRGGBB Light + Dark), asset_manage_image (scales/vector + preserves-vector-representation), asset_read_info (Contents.json), asset_delete (safe), asset_validate_actool (xcrun actool --compile)

asset_generate_appicon (iOS, macOS, watchOS, tvOS, visionOS — 42 slots, sips -z if baseImagePath)

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)

simctl_get_screen_analysis (sips → imagePath + resolution for Vision LLM), simctl_inspect_ui_tree (accessibility tree with center), simctl_tap_by_text (exact/partial + center click), simctl_fill_field (clearFirst + keystroke)

simctl_set_appearance (light/dark — xcrun simctl ui appearance), simctl_set_dynamic_type (Dynamic Type 12 categories), simctl_manage_storekit (load/clear/buy/refund), simctl_simulate_event (incoming_call/network_offline/online), simctl_send_push (APNs object → simctl push)

Full reference with JSON Schema + copy-paste examples → docs/tools.md

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 (52 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

Details → docs/development.md

Modular packs that teach your AI agent when to use each tool. Easy installer via Make:

make install          # 1. MCP server (Yarn)
make install-skills   # 2. Skills → ~/.agents/skills, ~/.claude/skills, ~/.codex/skills, ~/.config/opencode/skills
make test             # 3. Verify 52 tools
make list-skills      # list installed
make uninstall-skills # uninstall

Includes: xcode-mpc (52, main), xcode-build (8), xcode-simulator-vision (20), xcode-assets (7), xcode-package (11). See skills/README.md and docs/skills.md. Manual: ./scripts/install-skills.sh --dry-run.

# Without Make:
python3 scripts/smoke_test.py
# STDERR: ✅ Xcode MCP Server started — 52 tools
# ✓ tools/list: 52 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[52]: Strict JSON Schema (additionalProperties:false)
├── Handlers[52]: 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)

See docs/architecture.md for single-file decision, OpenCode → stdin → handler → xcrun → stdout flow.

# 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

Issues: Bug Report · Feature Request · PR Template

CI runs on macos-14 and ubuntu-latest — your PR is tested automatically.

MIT © YanxReal — see LICENSE.

• Repo: https://github.com/YanxReal/Xcode-MPC
• MCP Spec: https://modelcontextprotocol.io
• SDK: https://github.com/modelcontextprotocol/typescript-sdk
• Yarn Berry: https://yarnpkg.com/getting-started
• Xcode: https://developer.apple.com/xcode/