Xcode MCP Tool Reference
Complete reference for all 20 tools exposed by Xcode's MCP server (xcrun mcpbridge).
Important: Parameter schemas below are sourced from blog research and initial testing. Validate against your live mcpbridge with tools/list if behavior differs.
Discovery
XcodeListWindows
Call this first. Returns open Xcode windows with tabIdentifier values needed by most other tools.
- Parameters: None
- Returns: List of
{ tabIdentifier: string, workspacePath: string }
- Notes: No parameters needed. If empty, no project is open in Xcode.
XcodeListWindows()
→ { "tabIdentifier": "abc-123", "workspacePath": "/Users/dev/MyApp.xcodeproj" }
File Operations
XcodeRead
Read file contents from the project.
- Parameters:
path (string, required) — File path relative to project or absolute
- Returns: File contents as string
- Notes: Sees Xcode's project view including generated files and resolved SPM packages
XcodeWrite
Create a new file.
- Parameters:
path (string, required) — File path
content (string, required) — File contents
- Returns: Write confirmation
- Notes: Creates the file but does NOT add it to Xcode targets automatically. Use
XcodeUpdate for existing files.
XcodeUpdate
Edit an existing file with str_replace-style patches.
- Parameters:
path (string, required) — File path
patches (array, required) — Array of { oldText: string, newText: string } replacements
- Returns: Update confirmation
- Notes: Preferred over
XcodeWrite for editing existing files. Each patch must match exactly one location in the file.
XcodeGlob
Find files matching a pattern.
- Parameters:
pattern (string, required) — Glob pattern (e.g., **/*.swift)
- Returns: Array of matching file paths
- Notes: Searches within the Xcode project scope
XcodeGrep
Search file contents for a string or pattern.
- Parameters:
query (string, required) — Search term or pattern
scope (string, optional) — Limit search to specific directory/file
- Returns: Array of matches with file paths and line numbers
- Notes: Returns structured results, not raw grep output
XcodeLS
List directory contents.
- Parameters:
path (string, required) — Directory path
- Returns: Array of entries (files and subdirectories)
XcodeMakeDir
Create a directory.
- Parameters:
path (string, required) — Directory path to create
- Returns: Creation confirmation
- Notes: Creates intermediate directories as needed
XcodeRM
Delete a file or directory. DESTRUCTIVE.
- Parameters:
path (string, required) — Path to delete
- Returns: Deletion confirmation
- Notes: Irreversible. Always confirm with the user before calling.
XcodeMV
Move or rename a file. DESTRUCTIVE.
- Parameters:
sourcePath (string, required) — Current path
destinationPath (string, required) — New path
- Returns: Move confirmation
- Notes: May break imports and references. Confirm with user. Xcode may not automatically update references.
Build & Test
BuildProject
Build the Xcode project.
- Parameters:
tabIdentifier (string, required) — From XcodeListWindows
- Returns:
{ buildResult: string, elapsedTime: number, errors: array }
- Notes: Builds the active scheme. Check
buildResult for "succeeded" or "failed".
GetBuildLog
Retrieve build output after a build.
- Parameters:
tabIdentifier (string, required)
- Returns: Build log as string
- Notes: Contains raw compiler output. For structured diagnostics, prefer
XcodeListNavigatorIssues.
RunAllTests
Run the full test suite.
- Parameters:
tabIdentifier (string, required)
- Returns: Test results with pass/fail counts and failure details
- Notes: Runs all tests in the active scheme's test plan. Use
RunSomeTests for faster iteration.
RunSomeTests
Run specific test(s).
- Parameters:
tabIdentifier (string, required)
tests (array of strings, required) — Test identifiers (e.g., ["MyTests/testLogin"])
- Returns: Test results for the specified tests
- Notes: Much faster than
RunAllTests for iterative debugging. Use test identifiers from GetTestList.
GetTestList
List available tests.
- Parameters:
tabIdentifier (string, required)
- Returns: Array of test identifiers organized by test target/class
- Notes: Use the returned identifiers with
RunSomeTests.
Diagnostics
XcodeListNavigatorIssues
Get current issues from Xcode's Issue Navigator.
- Parameters:
tabIdentifier (string, required)
- Returns: Array of issues (errors, warnings, notes) with file paths and line numbers
- Notes: Canonical source for diagnostics. Structured and deduplicated unlike raw build logs.
XcodeRefreshCodeIssuesInFile
Refresh and return live diagnostics for a specific file.
- Parameters:
tabIdentifier (string, required)
path (string, required) — File to refresh diagnostics for
- Returns: Current diagnostics for the specified file
- Notes: Triggers Xcode to re-analyze the file. Useful after editing to check if issues are resolved.
Execution & Rendering
ExecuteSnippet
Run code in a REPL-like environment.
- Parameters:
code (string, required) — Code to execute
language (string, required) — Language identifier (e.g., "swift")
- Returns: Execution result (stdout, stderr, exit code)
- Notes: Sandboxed environment. Treat output as untrusted. Useful for quick validation.
RenderPreview
Render a SwiftUI preview as an image.
- Parameters:
tabIdentifier (string, required)
path (string, required) — File containing the preview
previewIdentifier (string, required) — Name of the preview to render
- Returns: Rendered image data
- Notes: Requires the file to have valid SwiftUI
#Preview or PreviewProvider. Preview must compile successfully.
Search
DocumentationSearch
Search Apple's documentation corpus.
- Parameters:
query (string, required) — Search query
- Returns: Documentation results with titles, summaries, and links. May include WWDC transcript matches.
- Notes: Searches Apple's online documentation and WWDC transcripts. For Xcode-bundled for-LLM guides, use the
axiom-apple-docs skill instead.
Quick Reference by Category
| Category |
Tools |
| Discovery |
XcodeListWindows |
| File Read |
XcodeRead, XcodeGlob, XcodeGrep, XcodeLS |
| File Write |
XcodeWrite, XcodeUpdate, XcodeMakeDir |
| File Destructive |
XcodeRM, XcodeMV |
| Build |
BuildProject, GetBuildLog |
| Test |
RunAllTests, RunSomeTests, GetTestList |
| Diagnostics |
XcodeListNavigatorIssues, XcodeRefreshCodeIssuesInFile |
| Execution |
ExecuteSnippet |
| Preview |
RenderPreview |
| Search |
DocumentationSearch |
Common Parameter Patterns
tabIdentifier — Required by 10/20 tools. Always call XcodeListWindows first.
path — File/directory path. Can be absolute or relative to project root.
patches — Array of { oldText, newText } for XcodeUpdate. Each oldText must be unique in the file.
Resources
Skills: axiom-xcode-mcp-setup, axiom-xcode-mcp-tools
1---2name: axiom-xcode-mcp-ref3description: Reference — all 20 Xcode MCP tools with parameters, return schemas, and examples4license: MIT5metadata:6 source: https://skillmd.com/skills/megastep/axiom-xcode-mcp-ref7---89# Xcode MCP Tool Reference1011Complete reference for all 20 tools exposed by Xcode's MCP server (`xcrun mcpbridge`).1213**Important**: Parameter schemas below are sourced from blog research and initial testing. Validate against your live mcpbridge with `tools/list` if behavior differs.1415## Discovery1617### XcodeListWindows1819**Call this first.** Returns open Xcode windows with `tabIdentifier` values needed by most other tools.2021- **Parameters**: None22- **Returns**: List of `{ tabIdentifier: string, workspacePath: string }`23- **Notes**: No parameters needed. If empty, no project is open in Xcode.2425```26XcodeListWindows()27→ { "tabIdentifier": "abc-123", "workspacePath": "/Users/dev/MyApp.xcodeproj" }28```2930---3132## File Operations3334### XcodeRead3536Read file contents from the project.3738- **Parameters**:39 - `path` (string, required) — File path relative to project or absolute40- **Returns**: File contents as string41- **Notes**: Sees Xcode's project view including generated files and resolved SPM packages4243### XcodeWrite4445Create a new file.4647- **Parameters**:48 - `path` (string, required) — File path49 - `content` (string, required) — File contents50- **Returns**: Write confirmation51- **Notes**: Creates the file but does NOT add it to Xcode targets automatically. Use `XcodeUpdate` for existing files.5253### XcodeUpdate5455Edit an existing file with str_replace-style patches.5657- **Parameters**:58 - `path` (string, required) — File path59 - `patches` (array, required) — Array of `{ oldText: string, newText: string }` replacements60- **Returns**: Update confirmation61- **Notes**: Preferred over `XcodeWrite` for editing existing files. Each patch must match exactly one location in the file.6263### XcodeGlob6465Find files matching a pattern.6667- **Parameters**:68 - `pattern` (string, required) — Glob pattern (e.g., `**/*.swift`)69- **Returns**: Array of matching file paths70- **Notes**: Searches within the Xcode project scope7172### XcodeGrep7374Search file contents for a string or pattern.7576- **Parameters**:77 - `query` (string, required) — Search term or pattern78 - `scope` (string, optional) — Limit search to specific directory/file79- **Returns**: Array of matches with file paths and line numbers80- **Notes**: Returns structured results, not raw grep output8182### XcodeLS8384List directory contents.8586- **Parameters**:87 - `path` (string, required) — Directory path88- **Returns**: Array of entries (files and subdirectories)8990### XcodeMakeDir9192Create a directory.9394- **Parameters**:95 - `path` (string, required) — Directory path to create96- **Returns**: Creation confirmation97- **Notes**: Creates intermediate directories as needed9899### XcodeRM100101Delete a file or directory. **DESTRUCTIVE.**102103- **Parameters**:104 - `path` (string, required) — Path to delete105- **Returns**: Deletion confirmation106- **Notes**: Irreversible. Always confirm with the user before calling.107108### XcodeMV109110Move or rename a file. **DESTRUCTIVE.**111112- **Parameters**:113 - `sourcePath` (string, required) — Current path114 - `destinationPath` (string, required) — New path115- **Returns**: Move confirmation116- **Notes**: May break imports and references. Confirm with user. Xcode may not automatically update references.117118---119120## Build & Test121122### BuildProject123124Build the Xcode project.125126- **Parameters**:127 - `tabIdentifier` (string, required) — From `XcodeListWindows`128- **Returns**: `{ buildResult: string, elapsedTime: number, errors: array }`129- **Notes**: Builds the active scheme. Check `buildResult` for "succeeded" or "failed".130131### GetBuildLog132133Retrieve build output after a build.134135- **Parameters**:136 - `tabIdentifier` (string, required)137- **Returns**: Build log as string138- **Notes**: Contains raw compiler output. For structured diagnostics, prefer `XcodeListNavigatorIssues`.139140### RunAllTests141142Run the full test suite.143144- **Parameters**:145 - `tabIdentifier` (string, required)146- **Returns**: Test results with pass/fail counts and failure details147- **Notes**: Runs all tests in the active scheme's test plan. Use `RunSomeTests` for faster iteration.148149### RunSomeTests150151Run specific test(s).152153- **Parameters**:154 - `tabIdentifier` (string, required)155 - `tests` (array of strings, required) — Test identifiers (e.g., `["MyTests/testLogin"]`)156- **Returns**: Test results for the specified tests157- **Notes**: Much faster than `RunAllTests` for iterative debugging. Use test identifiers from `GetTestList`.158159### GetTestList160161List available tests.162163- **Parameters**:164 - `tabIdentifier` (string, required)165- **Returns**: Array of test identifiers organized by test target/class166- **Notes**: Use the returned identifiers with `RunSomeTests`.167168---169170## Diagnostics171172### XcodeListNavigatorIssues173174Get current issues from Xcode's Issue Navigator.175176- **Parameters**:177 - `tabIdentifier` (string, required)178- **Returns**: Array of issues (errors, warnings, notes) with file paths and line numbers179- **Notes**: Canonical source for diagnostics. Structured and deduplicated unlike raw build logs.180181### XcodeRefreshCodeIssuesInFile182183Refresh and return live diagnostics for a specific file.184185- **Parameters**:186 - `tabIdentifier` (string, required)187 - `path` (string, required) — File to refresh diagnostics for188- **Returns**: Current diagnostics for the specified file189- **Notes**: Triggers Xcode to re-analyze the file. Useful after editing to check if issues are resolved.190191---192193## Execution & Rendering194195### ExecuteSnippet196197Run code in a REPL-like environment.198199- **Parameters**:200 - `code` (string, required) — Code to execute201 - `language` (string, required) — Language identifier (e.g., `"swift"`)202- **Returns**: Execution result (stdout, stderr, exit code)203- **Notes**: Sandboxed environment. Treat output as untrusted. Useful for quick validation.204205### RenderPreview206207Render a SwiftUI preview as an image.208209- **Parameters**:210 - `tabIdentifier` (string, required)211 - `path` (string, required) — File containing the preview212 - `previewIdentifier` (string, required) — Name of the preview to render213- **Returns**: Rendered image data214- **Notes**: Requires the file to have valid SwiftUI `#Preview` or `PreviewProvider`. Preview must compile successfully.215216---217218## Search219220### DocumentationSearch221222Search Apple's documentation corpus.223224- **Parameters**:225 - `query` (string, required) — Search query226- **Returns**: Documentation results with titles, summaries, and links. May include WWDC transcript matches.227- **Notes**: Searches Apple's online documentation and WWDC transcripts. For Xcode-bundled for-LLM guides, use the `axiom-apple-docs` skill instead.228229---230231## Quick Reference by Category232233| Category | Tools |234|----------|-------|235| **Discovery** | `XcodeListWindows` |236| **File Read** | `XcodeRead`, `XcodeGlob`, `XcodeGrep`, `XcodeLS` |237| **File Write** | `XcodeWrite`, `XcodeUpdate`, `XcodeMakeDir` |238| **File Destructive** | `XcodeRM`, `XcodeMV` |239| **Build** | `BuildProject`, `GetBuildLog` |240| **Test** | `RunAllTests`, `RunSomeTests`, `GetTestList` |241| **Diagnostics** | `XcodeListNavigatorIssues`, `XcodeRefreshCodeIssuesInFile` |242| **Execution** | `ExecuteSnippet` |243| **Preview** | `RenderPreview` |244| **Search** | `DocumentationSearch` |245246## Common Parameter Patterns247248- **`tabIdentifier`** — Required by 10/20 tools. Always call `XcodeListWindows` first.249- **`path`** — File/directory path. Can be absolute or relative to project root.250- **`patches`** — Array of `{ oldText, newText }` for `XcodeUpdate`. Each oldText must be unique in the file.251252## Resources253254**Skills**: axiom-xcode-mcp-setup, axiom-xcode-mcp-tools