kurko/axiom-xcode-mcp-ref

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