Xcode MCP Usage Guidelines

Xcode MCP tools consume significant tokens. This skill defines when to use Xcode MCP and when to prefer standard tools.

Complete Xcode MCP Tools Reference

Window & Project Management

Tool	Description	Token Cost
mcp__xcode__XcodeListWindows	List open Xcode windows (get tabIdentifier)	Low ✓

Build Operations

Tool	Description	Token Cost
mcp__xcode__BuildProject	Build the Xcode project	Medium ✓
mcp__xcode__GetBuildLog	Get build log with errors/warnings	Medium ✓
mcp__xcode__XcodeListNavigatorIssues	List issues in Issue Navigator	Low ✓

Testing

Tool	Description	Token Cost
mcp__xcode__GetTestList	Get available tests from test plan	Low ✓
mcp__xcode__RunAllTests	Run all tests	Medium
mcp__xcode__RunSomeTests	Run specific tests (preferred)	Medium ✓

Preview & Execution

Tool	Description	Token Cost
mcp__xcode__RenderPreview	Render SwiftUI Preview snapshot	Medium ✓
mcp__xcode__ExecuteSnippet	Execute code snippet in file context	Medium ✓

Diagnostics

Tool	Description	Token Cost
mcp__xcode__XcodeRefreshCodeIssuesInFile	Get compiler diagnostics for specific file	Low ✓
mcp__ide__getDiagnostics	Get SourceKit diagnostics (all open files)	Low ✓

Documentation

Tool	Description	Token Cost
mcp__xcode__DocumentationSearch	Search Apple Developer Documentation	Low ✓

File Operations (HIGH TOKEN - NEVER USE)

Tool	Alternative	Why
mcp__xcode__XcodeRead	Read tool	High token consumption
mcp__xcode__XcodeWrite	Write tool	High token consumption
mcp__xcode__XcodeUpdate	Edit tool	High token consumption
mcp__xcode__XcodeGrep	rg / Grep tool	High token consumption
mcp__xcode__XcodeGlob	Glob tool	High token consumption
mcp__xcode__XcodeLS	ls command	High token consumption
mcp__xcode__XcodeRM	rm command	High token consumption
mcp__xcode__XcodeMakeDir	mkdir command	High token consumption
mcp__xcode__XcodeMV	mv command	High token consumption

---

Recommended Workflows

1. Code Change & Build Flow

1. Search code      → rg "pattern" --type swift
2. Read file        → Read tool
3. Edit file        → Edit tool
4. Syntax check     → mcp__ide__getDiagnostics
5. Build            → mcp__xcode__BuildProject
6. Check errors     → mcp__xcode__GetBuildLog (if build fails)

2. Test Writing & Running Flow

1. Read test file   → Read tool
2. Write/edit test  → Edit tool
3. Get test list    → mcp__xcode__GetTestList
4. Run tests        → mcp__xcode__RunSomeTests (specific tests)
5. Check results    → Review test output

3. SwiftUI Preview Flow

1. Edit view        → Edit tool
2. Render preview   → mcp__xcode__RenderPreview
3. Iterate          → Repeat as needed

4. Debug Flow

1. Check diagnostics → mcp__ide__getDiagnostics (quick syntax check)
2. Build project     → mcp__xcode__BuildProject
3. Get build log     → mcp__xcode__GetBuildLog (severity: error)
4. Fix issues        → Edit tool
5. Rebuild           → mcp__xcode__BuildProject

5. Documentation Search

1. Search docs       → mcp__xcode__DocumentationSearch
2. Review results    → Use information in implementation

---

Fallback Commands (When MCP Unavailable)

If Xcode MCP is disconnected or unavailable, use these xcodebuild commands:

Build Commands

# Debug build (simulator) - replace <SchemeName> with your project's scheme
xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# Release build (device)
xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build

# Build with workspace (for CocoaPods projects)
xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# Build with project file
xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# List available schemes
xcodebuild -list

Test Commands

# Run all tests
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -configuration Debug

# Run specific test class
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>

# Run specific test method
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>/<testMethodName>

# Run with code coverage
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -configuration Debug -enableCodeCoverage YES

# List available simulators
xcrun simctl list devices available

Clean Build

xcodebuild clean -scheme <SchemeName>

---

Quick Reference

USE Xcode MCP For:

• ✅ BuildProject - Building
• ✅ GetBuildLog - Build errors
• ✅ RunSomeTests - Running specific tests
• ✅ GetTestList - Listing tests
• ✅ RenderPreview - SwiftUI previews
• ✅ ExecuteSnippet - Code execution
• ✅ DocumentationSearch - Apple docs
• ✅ XcodeListWindows - Get tabIdentifier
• ✅ mcp__ide__getDiagnostics - SourceKit errors

NEVER USE Xcode MCP For:

• ❌ XcodeRead → Use Read tool
• ❌ XcodeWrite → Use Write tool
• ❌ XcodeUpdate → Use Edit tool
• ❌ XcodeGrep → Use rg or Grep tool
• ❌ XcodeGlob → Use Glob tool
• ❌ XcodeLS → Use ls command
• ❌ File operations → Use standard tools

---

Token Efficiency Summary

Operation	Best Choice	Token Impact
Quick syntax check	mcp__ide__getDiagnostics	🟢 Low
Full build	mcp__xcode__BuildProject	🟡 Medium
Run specific tests	mcp__xcode__RunSomeTests	🟡 Medium
Run all tests	mcp__xcode__RunAllTests	🟠 High
Read file	Read tool	🟠 High
Edit file	Edit tool	🟠 High
Search code	rg / Grep	🟢 Low
List files	ls / Glob	🟢 Low