Xcode Tools Documentation

A comprehensive reference for the Xcode MCP Server aka Xcode Tools. These tools enable AI assistants to interact with Xcode workspaces — managing files, building projects, running tests, rendering previews, and more.

Apple Documentation

• Setting up coding intelligence
• Writing code with intelligence in Xcode
• Giving agentic coding tools access to Xcode

Prerequisites

• Xcode 26.3+ installed and running with an open workspace
• MCP server configured with Xcode integration

Note: Most tools require a tabIdentifier parameter that identifies which Xcode workspace tab to operate on.

Installation

Add the Xcode MCP server to your coding tool via xcrun mcpbridge:

Claude Code:

claude mcp add --transport stdio xcode -- xcrun mcpbridge

Codex:

codex mcp add xcode -- xcrun mcpbridge

Verify with claude mcp list or codex mcp list.

Schema

tools.json contains the full MCP tool definitions (name, title, description, input/output schemas) generated directly from xcrun mcpbridge.

Table of Contents

• Workspace
  • XcodeListWindows
• File Operations
  • XcodeLS
  • XcodeGlob
  • XcodeGrep
  • XcodeRead
  • XcodeWrite
  • XcodeUpdate
  • XcodeMakeDir
  • XcodeMV
  • XcodeRM
• Build & Run
  • BuildProject
  • GetBuildLog
  • ExecuteSnippet
• Testing
  • GetTestList
  • RunAllTests
  • RunSomeTests
• Diagnostics
  • XcodeRefreshCodeIssuesInFile
  • XcodeListNavigatorIssues
• Preview
  • RenderPreview
• Documentation
  • DocumentationSearch

Workspace

XcodeListWindows

Lists current Xcode windows and their workspace information. Use this to obtain tabIdentifier values needed by all other tools.

Parameters: None

Example:

XcodeListWindows()

File Operations

XcodeLS

Lists files and directories in the Xcode project structure at a given path. Operates on the project navigator hierarchy, not the filesystem.

Example:

XcodeLS(tabIdentifier: "...", path: "MyApp/Sources/")

XcodeGlob

Finds files in the Xcode project matching wildcard patterns. Supports *, **, ?, [abc], and {swift,m} syntax.

Example:

XcodeGlob(tabIdentifier: "...", pattern: "**/*.swift")

XcodeGrep

Searches file contents using regex patterns within the Xcode project structure.

Example:

XcodeGrep(
  tabIdentifier: "...",
  pattern: "func viewDidLoad",
  type: "swift",
  outputMode: "content",
  linesAfter: 5
)

XcodeRead

Reads file contents with line numbers (cat -n format). Supports offset/limit for large files.

Example:

XcodeRead(tabIdentifier: "...", filePath: "MyApp/Sources/ContentView.swift")

XcodeWrite

Creates or overwrites files in the Xcode project. Automatically adds new files to the project structure.

Example:

XcodeWrite(
  tabIdentifier: "...",
  filePath: "MyApp/Sources/NewFeature.swift",
  content: "import Foundation\n\nstruct NewFeature {\n}\n"
)

XcodeUpdate

Edits files by finding and replacing text. Operates on project structure paths.

Example:

XcodeUpdate(
  tabIdentifier: "...",
  filePath: "MyApp/Sources/ContentView.swift",
  oldString: "Hello, World!",
  newString: "Hello, SwiftUI!"
)

XcodeMakeDir

Creates directories and groups in the Xcode project navigator.

Example:

XcodeMakeDir(tabIdentifier: "...", directoryPath: "MyApp/Sources/ViewModels")

XcodeMV

Moves, copies, or renames files and directories in the project navigator.

Example:

XcodeMV(
  tabIdentifier: "...",
  sourcePath: "MyApp/Sources/OldName.swift",
  destinationPath: "MyApp/Sources/NewName.swift"
)

XcodeRM

Removes files and directories from the Xcode project. Optionally deletes underlying filesystem files.

Example:

XcodeRM(tabIdentifier: "...", path: "MyApp/Sources/Deprecated.swift")

Build & Run

BuildProject

Builds the Xcode project using the active scheme and waits for completion.

Example:

BuildProject(tabIdentifier: "...")

GetBuildLog

Retrieves build log entries from the current or most recent build. Filter by severity, file pattern, or message regex.

Example:

GetBuildLog(tabIdentifier: "...", severity: "warning")

ExecuteSnippet

Builds and runs a code snippet in the context of a specific source file. The snippet has access to all declarations in that file, including fileprivate ones. Output comes from print statements.

Note: Only works with source files in targets that build apps, frameworks, libraries, or CLI executables.

Example:

ExecuteSnippet(
  tabIdentifier: "...",
  sourceFilePath: "MyApp/Sources/Models/User.swift",
  codeSnippet: "let user = User(name: \"Test\")\nprint(user)"
)

Testing

GetTestList

Gets all available tests from the active scheme's active test plan. Results are limited to 100 tests. The complete list is written to fullTestListPath in grep-friendly format — use grep with keys like TEST_TARGET, TEST_IDENTIFIER, or TEST_FILE_PATH to find specific tests.

Example:

GetTestList(tabIdentifier: "...")

RunAllTests

Runs every test in the active scheme's active test plan.

Example:

RunAllTests(tabIdentifier: "...")

RunSomeTests

Runs specific tests by target and identifier. Use GetTestList first to discover available test identifiers.

Each test specifier object:

Example:

RunSomeTests(
  tabIdentifier: "...",
  tests: [
    { "targetName": "MyAppTests", "testIdentifier": "MyAppTests/LoginTests/testValidLogin" }
  ]
)

Diagnostics

XcodeRefreshCodeIssuesInFile

Retrieves current compiler diagnostics (errors, warnings, notes) for a specific file.

Example:

XcodeRefreshCodeIssuesInFile(
  tabIdentifier: "...",
  filePath: "MyApp/Sources/ContentView.swift"
)

XcodeListNavigatorIssues

Lists issues from Xcode's Issue Navigator, including build errors, package resolution problems, and workspace configuration issues.

Example:

XcodeListNavigatorIssues(tabIdentifier: "...", severity: "warning")

Preview

RenderPreview

Builds and renders a SwiftUI preview, returning a snapshot of the resulting UI.

Example:

RenderPreview(
  tabIdentifier: "...",
  sourceFilePath: "MyApp/Sources/Views/ProfileView.swift"
)

Documentation

DocumentationSearch

Searches Apple Developer Documentation using semantic matching. Useful for looking up APIs, frameworks, and usage patterns.

Author

Artem Novichkov, https://artemnovichkov.com