Xcode MCP Usage Guidelines

Xcode MCP tools are accessed via mcporter CLI, which bridges MCP servers to standard command-line tools. This skill defines when to use Xcode MCP and when to prefer standard tools.

Setup

Xcode MCP must be configured in ~/.mcporter/mcporter.json:

{
  "mcpServers": {
    "xcode": {
      "command": "xcrun",
      "args": ["mcpbridge"],
      "env": {}
    }
  }
}

Verify the connection:

mcporter list xcode

---

Calling Tools

All Xcode MCP tools are called via mcporter:

# List available tools
mcporter list xcode

# Call a tool with key:value args
mcporter call xcode.<tool_name> param1:value1 param2:value2

# Call with function-call syntax
mcporter call 'xcode.<tool_name>(param1: "value1", param2: "value2")'

---

Complete Xcode MCP Tools Reference

Window & Project Management

Tool	mcporter call	Token Cost
List open Xcode windows (get tabIdentifier)	mcporter call xcode.XcodeListWindows	Low ✓

Build Operations

Tool	mcporter call	Token Cost
Build the Xcode project	mcporter call xcode.BuildProject	Medium ✓
Get build log with errors/warnings	mcporter call xcode.GetBuildLog	Medium ✓
List issues in Issue Navigator	mcporter call xcode.XcodeListNavigatorIssues	Low ✓

Testing

Tool	mcporter call	Token Cost
Get available tests from test plan	mcporter call xcode.GetTestList	Low ✓
Run all tests	mcporter call xcode.RunAllTests	Medium
Run specific tests (preferred)	mcporter call xcode.RunSomeTests	Medium ✓

Preview & Execution

Tool	mcporter call	Token Cost
Render SwiftUI Preview snapshot	mcporter call xcode.RenderPreview	Medium ✓
Execute code snippet in file context	mcporter call xcode.ExecuteSnippet	Medium ✓

Diagnostics

Tool	mcporter call	Token Cost
Get compiler diagnostics for specific file	mcporter call xcode.XcodeRefreshCodeIssuesInFile	Low ✓
Get SourceKit diagnostics (all open files)	mcporter call xcode.getDiagnostics	Low ✓

Documentation

Tool	mcporter call	Token Cost
Search Apple Developer Documentation	mcporter call xcode.DocumentationSearch	Low ✓

File Operations (HIGH TOKEN - NEVER USE)

MCP Tool	Use Instead	Why
xcode.XcodeRead	Read tool / cat	High token consumption
xcode.XcodeWrite	Write tool	High token consumption
xcode.XcodeUpdate	Edit tool	High token consumption
xcode.XcodeGrep	rg / grep	High token consumption
xcode.XcodeGlob	find / glob	High token consumption
xcode.XcodeLS	ls command	High token consumption
xcode.XcodeRM	rm command	High token consumption
xcode.XcodeMakeDir	mkdir command	High token consumption
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 / cat
3. Edit file        → Edit tool
4. Syntax check     → mcporter call xcode.getDiagnostics
5. Build            → mcporter call xcode.BuildProject
6. Check errors     → mcporter call xcode.GetBuildLog (if build fails)

2. Test Writing & Running Flow

1. Read test file   → Read tool / cat
2. Write/edit test  → Edit tool
3. Get test list    → mcporter call xcode.GetTestList
4. Run tests        → mcporter call xcode.RunSomeTests (specific tests)
5. Check results    → Review test output

3. SwiftUI Preview Flow

1. Edit view        → Edit tool
2. Render preview   → mcporter call xcode.RenderPreview
3. Iterate          → Repeat as needed

4. Debug Flow

1. Check diagnostics → mcporter call xcode.getDiagnostics
2. Build project     → mcporter call xcode.BuildProject
3. Get build log     → mcporter call xcode.GetBuildLog severity:error
4. Fix issues        → Edit tool
5. Rebuild           → mcporter call xcode.BuildProject

5. Documentation Search

1. Search docs       → mcporter call xcode.DocumentationSearch query:"SwiftUI NavigationStack"
2. Review results    → Use information in implementation

---

Fallback Commands (When MCP or mcporter Unavailable)

If Xcode MCP is disconnected, mcporter is not installed, or the connection fails, use these xcodebuild commands directly:

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 mcporter + Xcode MCP For:

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

NEVER USE Xcode MCP For:

• ❌ xcode.XcodeRead → Use Read tool / cat
• ❌ xcode.XcodeWrite → Use Write tool
• ❌ xcode.XcodeUpdate → Use Edit tool
• ❌ xcode.XcodeGrep → Use rg or grep
• ❌ xcode.XcodeGlob → Use find / glob
• ❌ xcode.XcodeLS → Use ls command
• ❌ File operations → Use standard tools

---

Token Efficiency Summary

Operation	Best Choice	Token Impact
Quick syntax check	mcporter call xcode.getDiagnostics	🟢 Low
Full build	mcporter call xcode.BuildProject	🟡 Medium
Run specific tests	mcporter call xcode.RunSomeTests	🟡 Medium
Run all tests	mcporter call xcode.RunAllTests	🟠 High
Read file	Read tool / cat	🟢 Low
Edit file	Edit tool	🟢 Low
Search code	rg / grep	🟢 Low
List files	ls / find	🟢 Low