Guidelines for efficient Xcode MCP tool usage

by Ilker Ulusoy · CC0-1.0 license · updated Sep 9

Guidelines for efficient Xcode MCP tool usage. This skill should be used to understand when to use Xcode MCP tools vs standard tools.

Overview

Guidelines for efficient Xcode MCP tool usage. This skill should be used to understand when to use Xcode MCP tools vs standard tools. Xcode MCP consumes many tokens - use only for build, test, simulator, preview, and SourceKit diagnostics. Never use for file read/write/grep operations.

The prompt

198 lines · 6,757 characters · paste it into ChatGPT, Claude or Gemini

1	---
2	name: xcode-mcp
3	description: Guidelines for efficient Xcode MCP tool usage. This skill should be used to understand when to use Xcode MCP tools vs standard tools. Xcode MCP consumes many tokens - use only for build, test, simulator, preview, and SourceKit diagnostics. Never use for file read/write/grep operations.
4	---
5
6	# Xcode MCP Usage Guidelines
7
8	Xcode MCP tools consume significant tokens. This skill defines when to use Xcode MCP and when to prefer standard tools.
9
10	## Complete Xcode MCP Tools Reference
11
12	### Window & Project Management
13	\| Tool \| Description \| Token Cost \|
14	\|------\|-------------\|------------\|
15	\| `mcp__xcode__XcodeListWindows` \| List open Xcode windows (get tabIdentifier) \| Low ✓ \|
16
17	### Build Operations
18	\| Tool \| Description \| Token Cost \|
19	\|------\|-------------\|------------\|
20	\| `mcp__xcode__BuildProject` \| Build the Xcode project \| Medium ✓ \|
21	\| `mcp__xcode__GetBuildLog` \| Get build log with errors/warnings \| Medium ✓ \|
22	\| `mcp__xcode__XcodeListNavigatorIssues` \| List issues in Issue Navigator \| Low ✓ \|
23
24	### Testing
25	\| Tool \| Description \| Token Cost \|
26	\|------\|-------------\|------------\|
27	\| `mcp__xcode__GetTestList` \| Get available tests from test plan \| Low ✓ \|
28	\| `mcp__xcode__RunAllTests` \| Run all tests \| Medium \|
29	\| `mcp__xcode__RunSomeTests` \| Run specific tests (preferred) \| Medium ✓ \|
30
31	### Preview & Execution
32	\| Tool \| Description \| Token Cost \|
33	\|------\|-------------\|------------\|
34	\| `mcp__xcode__RenderPreview` \| Render SwiftUI Preview snapshot \| Medium ✓ \|
35	\| `mcp__xcode__ExecuteSnippet` \| Execute code snippet in file context \| Medium ✓ \|
36
37	### Diagnostics
38	\| Tool \| Description \| Token Cost \|
39	\|------\|-------------\|------------\|
40	\| `mcp__xcode__XcodeRefreshCodeIssuesInFile` \| Get compiler diagnostics for specific file \| Low ✓ \|
41	\| `mcp__ide__getDiagnostics` \| Get SourceKit diagnostics (all open files) \| Low ✓ \|
42
43	### Documentation
44	\| Tool \| Description \| Token Cost \|
45	\|------\|-------------\|------------\|
46	\| `mcp__xcode__DocumentationSearch` \| Search Apple Developer Documentation \| Low ✓ \|
47
48	### File Operations (HIGH TOKEN - NEVER USE)
49	\| Tool \| Alternative \| Why \|
50	\|------\|-------------\|-----\|
51	\| `mcp__xcode__XcodeRead` \| `Read` tool \| High token consumption \|
52	\| `mcp__xcode__XcodeWrite` \| `Write` tool \| High token consumption \|
53	\| `mcp__xcode__XcodeUpdate` \| `Edit` tool \| High token consumption \|
54	\| `mcp__xcode__XcodeGrep` \| `rg` / `Grep` tool \| High token consumption \|
55	\| `mcp__xcode__XcodeGlob` \| `Glob` tool \| High token consumption \|
56	\| `mcp__xcode__XcodeLS` \| `ls` command \| High token consumption \|
57	\| `mcp__xcode__XcodeRM` \| `rm` command \| High token consumption \|
58	\| `mcp__xcode__XcodeMakeDir` \| `mkdir` command \| High token consumption \|
59	\| `mcp__xcode__XcodeMV` \| `mv` command \| High token consumption \|
60
61	---
62
63	## Recommended Workflows
64
65	### 1. Code Change & Build Flow
66	```
67	1. Search code → rg "pattern" --type swift
68	2. Read file → Read tool
69	3. Edit file → Edit tool
70	4. Syntax check → mcp__ide__getDiagnostics
71	5. Build → mcp__xcode__BuildProject
72	6. Check errors → mcp__xcode__GetBuildLog (if build fails)
73	```
74
75	### 2. Test Writing & Running Flow
76	```
77	1. Read test file → Read tool
78	2. Write/edit test → Edit tool
79	3. Get test list → mcp__xcode__GetTestList
80	4. Run tests → mcp__xcode__RunSomeTests (specific tests)
81	5. Check results → Review test output
82	```
83
84	### 3. SwiftUI Preview Flow
85	```
86	1. Edit view → Edit tool
87	2. Render preview → mcp__xcode__RenderPreview
88	3. Iterate → Repeat as needed
89	```
90
91	### 4. Debug Flow
92	```
93	1. Check diagnostics → mcp__ide__getDiagnostics (quick syntax check)
94	2. Build project → mcp__xcode__BuildProject
95	3. Get build log → mcp__xcode__GetBuildLog (severity: error)
96	4. Fix issues → Edit tool
97	5. Rebuild → mcp__xcode__BuildProject
98	```
99
100	### 5. Documentation Search
101	```
102	1. Search docs → mcp__xcode__DocumentationSearch
103	2. Review results → Use information in implementation
104	```
105
106	---
107
108	## Fallback Commands (When MCP Unavailable)
109
110	If Xcode MCP is disconnected or unavailable, use these xcodebuild commands:
111
112	### Build Commands
113	```bash
114	# Debug build (simulator) - replace <SchemeName> with your project's scheme
115	xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build
116
117	# Release build (device)
118	xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build
119
120	# Build with workspace (for CocoaPods projects)
121	xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build
122
123	# Build with project file
124	xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build
125
126	# List available schemes
127	xcodebuild -list
128	```
129
130	### Test Commands
131	```bash
132	# Run all tests
133	xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
134	-destination "platform=iOS Simulator,name=iPhone 16" \
135	-configuration Debug
136
137	# Run specific test class
138	xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
139	-destination "platform=iOS Simulator,name=iPhone 16" \
140	-only-testing:<TestTarget>/<TestClassName>
141
142	# Run specific test method
143	xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
144	-destination "platform=iOS Simulator,name=iPhone 16" \
145	-only-testing:<TestTarget>/<TestClassName>/<testMethodName>
146
147	# Run with code coverage
148	xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
149	-configuration Debug -enableCodeCoverage YES
150
151	# List available simulators
152	xcrun simctl list devices available
153	```
154
155	### Clean Build
156	```bash
157	xcodebuild clean -scheme <SchemeName>
158
159	```
160
161	---
162
163	## Quick Reference
164
165	### USE Xcode MCP For:
166	- ✅ `BuildProject` - Building
167	- ✅ `GetBuildLog` - Build errors
168	- ✅ `RunSomeTests` - Running specific tests
169	- ✅ `GetTestList` - Listing tests
170	- ✅ `RenderPreview` - SwiftUI previews
171	- ✅ `ExecuteSnippet` - Code execution
172	- ✅ `DocumentationSearch` - Apple docs
173	- ✅ `XcodeListWindows` - Get tabIdentifier
174	- ✅ `mcp__ide__getDiagnostics` - SourceKit errors
175
176	### NEVER USE Xcode MCP For:
177	- ❌ `XcodeRead` → Use `Read` tool
178	- ❌ `XcodeWrite` → Use `Write` tool
179	- ❌ `XcodeUpdate` → Use `Edit` tool
180	- ❌ `XcodeGrep` → Use `rg` or `Grep` tool
181	- ❌ `XcodeGlob` → Use `Glob` tool
182	- ❌ `XcodeLS` → Use `ls` command
183	- ❌ File operations → Use standard tools
184
185	---
186
187	## Token Efficiency Summary
188
189	\| Operation \| Best Choice \| Token Impact \|
190	\|-----------\|-------------\|--------------\|
191	\| Quick syntax check \| `mcp__ide__getDiagnostics` \| 🟢 Low \|
192	\| Full build \| `mcp__xcode__BuildProject` \| 🟡 Medium \|
193	\| Run specific tests \| `mcp__xcode__RunSomeTests` \| 🟡 Medium \|
194	\| Run all tests \| `mcp__xcode__RunAllTests` \| 🟠 High \|
195	\| Read file \| `Read` tool \| 🟠 High \|
196	\| Edit file \| `Edit` tool \| 🟠 High\|
197	\| Search code \| `rg` / `Grep` \| 🟢 Low \|
198	\| List files \| `ls` / `Glob` \| 🟢 Low \|