Xcode Mcp Suite

File Operations (9 tools)

Build & Test (5 tools)

Diagnostics (2 tools)

Code Execution (1 tool)

Preview (1 tool)

Documentation (1 tool)

Windowing (1 tool)

Model Selection for Xcode Tasks

Pick the cheapest model that can handle the job. iOS/macOS work ranges from trivial to architecturally complex.

Sonnet 4.6 / Codex 5.3 (default — use for most work)

• File reads, glob, grep, ls — pure navigation
• Single-file edits (fix a typo, rename a variable, add a property)
• Running builds and reading build errors
• Running tests and interpreting results
• Screenshot → image analysis for simple UI checks
• Documentation searches
• Simulator interaction (tap, type, swipe) — just coordinates
• Build log parsing, issue triage
• Writing tests for existing code

Opus 4.6 / Codex 5.4 (escalate for hard problems)

• Multi-file refactors (rename across 10+ files, move types between modules)
• Architectural decisions (choosing patterns, designing protocols, module boundaries)
• Debugging complex build failures (linker errors, module resolution, SPM dependency conflicts)
• SwiftUI layout debugging (analyzing preview images + suggesting structural fixes)
• Writing new features from scratch (new views, new data models, new networking layers)
• Test infrastructure setup (custom XCTestCase subclasses, mock frameworks)
• Performance analysis (interpreting Instruments traces, suggesting optimizations)
• Diagnosing runtime crashes from simulator logs
• Any task that requires understanding how 3+ files interact

Rule of thumb

If the task is "read → edit one thing → build → verify" → Sonnet/Codex-5.3 If the task is "understand the architecture → design a solution → change multiple files → debug" → Opus/Codex-5.4

CRITICAL: Always Start With XcodeListWindows

Every tool (except DocumentationSearch) requires a tabIdentifier. Get it from XcodeListWindows first:

→ XcodeListWindows()
← { "message": "* tabIdentifier: windowtab1, workspacePath: /Users/you/MyApp.xcodeproj" }

Then pass tabIdentifier: "windowtab1" to every subsequent call.

Typical Dev Workflow

1. XcodeListWindows                          # get tabIdentifier
2. XcodeGlob { pattern: "**/*.swift" }       # discover project files
3. XcodeRead { filePath: "..." }             # read source code
4. XcodeUpdate { filePath, oldString, newString } # edit with str_replace
5. BuildProject { tabIdentifier }            # build → check errors
6. GetBuildLog { severity: "error" }         # see what's broken
7. XcodeListNavigatorIssues                  # all project issues
8. RunAllTests                               # run test suite
9. RenderPreview { filePath }                # visual audit → PNG
10. ExecuteSnippet { code: "..." }           # spot-check Swift logic
11. DocumentationSearch { query: "..." }     # look up Apple APIs + WWDC

SDK Usage (TypeScript)

import { withXcodeSession } from "@kleinpanic/xcode-mcp-sdk";

await withXcodeSession({ host: "collins-pro" }, async (s) => {
  // tabIdentifier managed automatically by XcodeSession

  // File operations
  const files = await s.glob("**/*.swift");
  const source = await s.readFile("Sources/App.swift");
  await s.updateFile("Sources/App.swift", "old code", "new code"); // oldString, newString

  // Build & test
  const build = await s.buildProject();
  const tests = await s.runAllTests();
  const specific = await s.runSomeTests(["MyAppTests/testLogin"]);

  // Diagnostics
  const issues = await s.listNavigatorIssues();
  const fileIssues = await s.refreshCodeIssuesInFile("Sources/App.swift");

  // Execute Swift (requires source file context)
  const result = await s.executeSnippet('print([1,2,3].map { $0 * 2 })', 'Sources/App.swift');

  // Preview → base64 PNG
  const preview = await s.renderPreview("Sources/Views/ContentView.swift");

  // Search Apple docs + WWDC transcripts
  const docs = await s.searchDocumentation("SwiftUI List");
});

CLI Commands

xcmcp build   --host collins-pro [--scheme MyApp]
xcmcp test    --host collins-pro [--scheme MyApp]
xcmcp repl    --host collins-pro '<swift code>'
xcmcp preview --host collins-pro --file Sources/Views/ContentView.swift
xcmcp screenshot --host collins-pro --mode simulator --out /tmp/ui.png
xcmcp docs    --host collins-pro "SwiftUI List"  # search Apple docs + WWDC
xcmcp test-some --host collins-pro MyTests/testLogin  # run specific tests
xcmcp call    <ToolName> '<json-args>'    # call any tool directly
xcmcp windows --host collins-pro          # list windows + tabIdentifiers
xcmcp list-tools                          # show all 20 tools + TCC markers

Visual See + Interact Loop

See (capture current state)

xcmcp screenshot --host collins-pro --mode simulator --out /tmp/sim.png
# Then use `image` tool to analyze the PNG and find UI element coords

Interact (control the simulator)

# Input
xcmcp ui tap   --host collins-pro 195 420     # tap at coords
xcmcp ui type  --host collins-pro "text"      # type into field
xcmcp ui swipe --host collins-pro 200 600 200 200   # scroll/swipe
xcmcp ui key   --host collins-pro 36          # Return key

# Simulator management
xcmcp ui list --host collins-pro              # list booted simulators
xcmcp ui list --host collins-pro --all        # list all available
xcmcp ui boot --host collins-pro "iPhone 16 Pro"  # boot a simulator
xcmcp ui shutdown --host collins-pro          # shut down booted sim
xcmcp ui open --host collins-pro              # open Simulator.app

# App lifecycle
xcmcp ui install --host collins-pro /path/to/MyApp.app
xcmcp ui launch --host collins-pro com.example.MyApp
xcmcp ui terminate --host collins-pro com.example.MyApp

# Logs
xcmcp ui log   --host collins-pro             # stream app logs

Full visual loop

# build → screenshot → analyze → interact → screenshot → verify
xcmcp build --host collins-pro
xcmcp screenshot --host collins-pro --mode simulator --out /tmp/s1.png
# → analyze with `image` tool → get button coords
xcmcp ui tap --host collins-pro 195 420
xcmcp screenshot --host collins-pro --mode simulator --out /tmp/s2.png
# → analyze to verify UI changed correctly

TCC/Automation Permission (IMPORTANT)

Some tools require macOS Automation (AppleEvents/TCC) permission:

Over SSH (our setup): The TCC dialog appears on the Mac's physical display, not in SSH. To fix: sit at collins-pro once, run any TCC tool (e.g. BuildProject), click "Allow" in the macOS dialog. After that, SSH sessions work without further prompts.

If the tool hangs indefinitely, the TCC dialog was never accepted — someone needs to physically click "Allow" on the Mac.

Troubleshooting

IMPORTANT: Correct Parameter Names (from Apple's API)

Some parameters have non-obvious names. These are verified against the actual tools/list output:

Full verified schemas: ~/codeWS/GitHub/kleinpanic/xcode-mcp-suite/docs/schemas/tools-list-rc1.json

Known Issues

mcpbridge v24582 (Xcode 26.3 build 17C529) — stdio bug

Status: Confirmed. mcpbridge only responds to initialize, then ignores ALL subsequent messages (tools/list, tools/call). Affects: Both SSH and local connections on collins-pro. Workaround: Use Claude Code or Codex directly on collins-pro (they work through the MCP SDK). The SSH proxy approach doesn't work until Apple fixes mcpbridge. Tested: Node.js spawn, Python subprocess, bash pipe — all only get 1 response.

XcodeBuildMCP alternative

For simulator management, debugging, and additional features not in Apple's 20 tools, see XcodeBuildMCP — a third-party MCP server that wraps xcodebuild directly (no mcpbridge dependency).

Reference

• Tools Reference — all 20 tools with full params
• Agent Integration Guide
• Apple Official Docs