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