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

Discovery

XcodeListWindows

Call this first. Returns open Xcode windows with

tabIdentifier

• 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

XcodeListWindows

XcodeRead

XcodeGlob

XcodeGrep

XcodeLS

XcodeWrite

XcodeUpdate

XcodeMakeDir

XcodeRM

XcodeMV

BuildProject

GetBuildLog

RunAllTests

RunSomeTests

GetTestList

XcodeListNavigatorIssues

XcodeRefreshCodeIssuesInFile

ExecuteSnippet

RenderPreview

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