Skip to main content
Glama

A Model Context Protocol (MCP) server that provides Xcode-related tools for integration with AI assistants and other MCP clients.

npm version CI CodeQL Licence: MIT

Table of contents

Related MCP server: XcodeBuildMCP

Overview

This project implements an MCP server that exposes Xcode operations as tools that can be invoked by AI agents via the MCP protocol. It enables programmatic interaction with Xcode projects through a standardised interface, optimised for agent-driven development workflows.

xcodebuildmcp2

Why?

The XcodeBuild MCP tool exists primarily to streamline and standardise interaction between AI agents and Xcode projects. By providing dedicated tools for common Xcode operations, it removes reliance on manual or potentially incorrect command-line invocations.

This ensures a reliable and efficient development process, allowing agents to seamlessly leverage Xcode's capabilities while reducing the risk of configuration errors.

Critically, this MCP enables AI agents to independently validate code changes by building projects, inspecting errors, and iterating autonomously. In contrast to user-driven tools like Sweetpad, XcodeBuild MCP empowers agents to automate these workflows effectively.

Features

The XcodeBuildMCP server provides the following tool capabilities:

Xcode project management

  • Discover Projects: Xcode projects and workspaces discovery

  • Build Operations: Platform-specific build tools for macOS, iOS simulator, and iOS device targets

  • Project Information: Tools to list schemes and show build settings for Xcode projects and workspaces

  • Clean Operations: Clean build products using xcodebuild's native clean action

  • Incremental build support: Lightning fast builds using incremental build support (experimental, opt-in required)

  • Project Scaffolding: Create new iOS and macOS projects from modern templates with workspace + SPM package architecture, customizable bundle identifiers, deployment targets, and device families

Swift Package Manager

  • Build Packages: Build Swift packages with configuration and architecture options

  • Run Tests: Execute Swift package test suites with filtering and parallel execution

  • Run Executables: Execute package binaries with timeout handling and background execution support

  • Process Management: List and stop long-running executables started with Swift Package tools

  • Clean Artifacts: Remove build artifacts and derived data for fresh builds

Simulator management

  • Simulator Control: List, boot, and open iOS simulators

  • App Deployment: Install and launch apps on iOS simulators

  • Log Capture: Capture run-time logs from a simulator

  • UI Automation: Interact with simulator UI elements (beta)

  • Screenshot: Capture screenshots from a simulator (beta)

App utilities

  • Bundle ID Extraction: Extract bundle identifiers from iOS and macOS app bundles

  • App Launching: Launch built applications on both simulators and macOS

Getting started

Prerequisites

  • macOS 14.5 or later

  • Xcode 16.x or later

  • Node 18.x or later

  • AXe 1.0.0 or later (optional, required for UI automation)

UI Automation

For UI automation features (tap, swipe, type etc.), you'll need to install AXe:

brew tap cameroncooke/axe
brew install axe

For more information about AXe and other installation methods, see the AXe repository.

Configure your MCP client

Quick install

For a quick install, you can use the following links:

  • Install MCP Server

Manual installation

Configure your MCP client (Windsurf, Cursor, Claude Desktop, Claude Code etc.) to use the XcodeBuildMCP server by ammending your client application's MCP configuration.

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Alternative installation method using mise

Alternatively, you can use XcodeBuildMCP without a specific installation of Node.js by using mise to install it:

# macOS (Homebrew)
brew install mise

# Other installation methods
# See https://mise.jdx.dev/getting-started.html

Then configure your MCP client to use mise to install XcodeBuildMCP:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.7.0",
        "--",
        "xcodebuildmcp"
      ]
    }
  }
}
NOTE

When using mise avoid using the @latest tag as mise will cache the package and may not update to the latest version automatically, instead prefer an explicit version number.

IMPORTANT

Please note that XcodeBuildMCP will request xcodebuild to skip macro validation. This is to avoid errors when building projects that use Swift Macros.

Incremental build support

XcodeBuildMCP includes experimental support for incremental builds. This feature is disabled by default and can be enabled by setting the INCREMENTAL_BUILDS_ENABLED environment variable to true:

To enable incremental builds, set the INCREMENTAL_BUILDS_ENABLED environment variable to true:

Example MCP client configuration:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ],
      "env": {
        "INCREMENTAL_BUILDS_ENABLED": "true"
      }        
    }
  }
}
IMPORTANT

Please note that incremental builds support is currently highly experimental and your mileage may vary. Please report any issues you encounter to theissue tracker.

Troubleshooting

If you encounter issues with XcodeBuildMCP, the diagnostic tool can help identify the problem by providing detailed information about your environment and dependencies.

Diagnostic Tool

The diagnostic tool is a standalone utility that checks your system configuration and reports on the status of all dependencies required by XcodeBuildMCP. It's particularly useful when reporting issues.

Using with npx

# Run the diagnostic tool using npx
npx xcodebuildmcp@1.7.0 xcodebuildmcp-diagnostic

Using with mise

# Run the diagnostic tool using mise
mise x npm:xcodebuildmcp@1.7.0 -- xcodebuildmcp-diagnostic

The diagnostic tool will output comprehensive information about:

  • System and Node.js environment

  • Xcode installation and configuration

  • Required dependencies (xcodebuild, AXe, etc.)

  • Environment variables affecting XcodeBuildMCP

  • Feature availability status

When reporting issues on GitHub, please include the full output from the diagnostic tool to help with troubleshooting.

MCP Server Logs

It can be helpful to have access to the log messages from the MCP server to identify any issues. The logs are captured by the client application, for example in Cursor:

Cursor:

find ~/Library/Application\ Support/Cursor/logs -name "Cursor MCP.log" -exec zip -r matching_logs.zip {} +

If your MCP client doesn't have log files you can run the server directly using the MCP Inspector tool see Debugging for more information on how to do this. Once running the MCP tool prints all log messages to it's error pane, which can be helpful in diagnosing issues.

Privacy

This project uses Sentry for error monitoring and diagnostics. Sentry helps us track issues, crashes, and unexpected errors to improve the reliability and stability of XcodeBuildMCP.

What is sent to Sentry?

  • Only error-level logs and diagnostic information are sent to Sentry by default.

  • Error logs may include details such as error messages, stack traces, and (in some cases) file paths or project names. You can review the sources in this repository to see exactly what is logged.

Opting Out of Sentry

  • If you do not wish to send error logs to Sentry, you can opt out by setting the environment variable SENTRY_DISABLED=true.

Example MCP client configuration:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ],
      "env": {
        "SENTRY_DISABLED": "true"
      }        
    }
  }
}

Selective tool registration

By default all tools are enabled but for some clients it may be useful to only enable specific tools to reduce the amount of context that is sent to the client. This can be achieved by setting specific environment variables in your clients MCP configuration.

Once you have enabled one or more tools or groups of tools all other tools will be disabled. For example, to enable only the simulator related tools, you can set the environment variable to XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true this will only expose tools for building, running and debugging on simulators

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ],
      "env": {
        "XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true"
      }        
    }
  }
}

You can find a list of available tools and detailed instructions on how to enable them in the TOOL_OPTIONS.md file.

Demos

Autonomously fixing build errors in Cursor

xcodebuildmcp3

Utilising the new UI automation and screen capture features

xcodebuildmcp4

Building and running iOS app in Claude Desktop

https://github.com/user-attachments/assets/e3c08d75-8be6-4857-b4d0-9350b26ef086

Contributing

Contributions are welcome! Here's how you can help improve XcodeBuildMCP.

See our CONTRIBUTING document for more information on how to configure your local environment and contribute to the project.

Licence

This project is licensed under the MIT License - see the LICENSE file for details.

MCP Server Verification

Glama.ai

MseeP.a

Available Tools

54 tools
boot_simB

Boots an iOS simulator. IMPORTANT: You MUST provide the simulatorUuid parameter. Example: boot_sim({ simulatorUuid: 'YOUR_UUID_HERE' })

Inputs: simulatorUuid (required).

build_ios_dev_projB

Builds an iOS app from a project file for a physical device. IMPORTANT: Requires projectPath and scheme. Example: build_ios_dev_proj({ projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyScheme' })

Inputs: projectPath (required), scheme (required), configuration, derivedDataPath, +2 more.

build_ios_dev_wsA

Builds an iOS app from a workspace for a physical device. IMPORTANT: Requires workspacePath and scheme. Example: build_ios_dev_ws({ workspacePath: '/path/to/MyProject.xcworkspace', scheme: 'MyScheme' })

Inputs: workspacePath (required), scheme (required), configuration, derivedDataPath, +2 more.

build_ios_sim_id_projB

Builds an iOS app from a project file for a specific simulator by UUID. IMPORTANT: Requires projectPath, scheme, and simulatorId. Example: build_ios_sim_id_proj({ projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyScheme', simulatorId: 'SIMULATOR_UUID' })

Inputs: projectPath (required), scheme (required), simulatorId (required), configuration, +4 more.

build_ios_sim_id_wsB

Builds an iOS app from a workspace for a specific simulator by UUID. IMPORTANT: Requires workspacePath, scheme, and simulatorId. Example: build_ios_sim_id_ws({ workspacePath: '/path/to/MyProject.xcworkspace', scheme: 'MyScheme', simulatorId: 'SIMULATOR_UUID' })

Inputs: workspacePath (required), scheme (required), simulatorId (required), configuration, +4 more.

build_ios_sim_name_projB

Builds an iOS app from a project file for a specific simulator by name. IMPORTANT: Requires projectPath, scheme, and simulatorName. Example: build_ios_sim_name_proj({ projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyScheme', simulatorName: 'iPhone 16' })

Inputs: projectPath (required), scheme (required), simulatorName (required), configuration, +4 more.

build_ios_sim_name_wsB

Builds an iOS app from a workspace for a specific simulator by name. IMPORTANT: Requires workspacePath, scheme, and simulatorName. Example: build_ios_sim_name_ws({ workspacePath: '/path/to/MyProject.xcworkspace', scheme: 'MyScheme', simulatorName: 'iPhone 16' })

Inputs: workspacePath (required), scheme (required), simulatorName (required), configuration, +4 more.

build_mac_projC

Builds a macOS app using xcodebuild from a project file.

Inputs: projectPath (required), scheme (required), configuration, derivedDataPath, +3 more.

build_mac_wsC

Builds a macOS app using xcodebuild from a workspace.

Inputs: workspacePath (required), scheme (required), configuration, derivedDataPath, +3 more.

build_run_ios_sim_id_projA

Builds and runs an iOS app from a project file on a simulator specified by UUID. IMPORTANT: Requires projectPath, scheme, and simulatorId. Example: build_run_ios_sim_id_proj({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme', simulatorId: 'SIMULATOR_UUID' })

Inputs: projectPath (required), scheme (required), simulatorId (required), configuration, +4 more.

build_run_ios_sim_id_wsA

Builds and runs an iOS app from a workspace on a simulator specified by UUID. IMPORTANT: Requires workspacePath, scheme, and simulatorId. Example: build_run_ios_sim_id_ws({ workspacePath: '/path/to/workspace', scheme: 'MyScheme', simulatorId: 'SIMULATOR_UUID' })

Inputs: workspacePath (required), scheme (required), simulatorId (required), configuration, +4 more.

build_run_ios_sim_name_projB

Builds and runs an iOS app from a project file on a simulator specified by name. IMPORTANT: Requires projectPath, scheme, and simulatorName. Example: build_run_ios_sim_name_proj({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme', simulatorName: 'iPhone 16' })

Inputs: projectPath (required), scheme (required), simulatorName (required), configuration, +4 more.

build_run_ios_sim_name_wsB

Builds and runs an iOS app from a workspace on a simulator specified by name. IMPORTANT: Requires workspacePath, scheme, and simulatorName. Example: build_run_ios_sim_name_ws({ workspacePath: '/path/to/workspace', scheme: 'MyScheme', simulatorName: 'iPhone 16' })

Inputs: workspacePath (required), scheme (required), simulatorName (required), configuration, +4 more.

build_run_mac_projB

Builds and runs a macOS app from a project file in one step.

Inputs: projectPath (required), scheme (required), configuration, derivedDataPath, +2 more.

build_run_mac_wsC

Builds and runs a macOS app from a workspace in one step.

Inputs: workspacePath (required), scheme (required), configuration, derivedDataPath, +2 more.

clean_projB

Cleans build products for a specific project file using xcodebuild. IMPORTANT: Requires projectPath. Scheme/Configuration are optional. Example: clean_proj({ projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyScheme' })

Inputs: projectPath (required), scheme, configuration, derivedDataPath, +1 more.

clean_wsA

Cleans build products for a specific workspace using xcodebuild. IMPORTANT: Requires workspacePath. Scheme/Configuration are optional. Example: clean_ws({ workspacePath: '/path/to/MyProject.xcworkspace', scheme: 'MyScheme' })

Inputs: workspacePath (required), scheme, configuration, derivedDataPath, +1 more.

discover_projsC

Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.

Inputs: workspaceRoot (required), scanPath, maxDepth.

get_ios_bundle_idA

Extracts the bundle identifier from an iOS app bundle (.app). IMPORTANT: You MUST provide the appPath parameter. Example: get_ios_bundle_id({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_get_ios_bundle_id.

Inputs: appPath (required).

get_ios_dev_app_path_projA

Gets the app bundle path for an iOS physical device application using a project file. IMPORTANT: Requires projectPath and scheme. Example: get_ios_dev_app_path_proj({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme' })

Inputs: projectPath (required), scheme (required), configuration.

get_ios_dev_app_path_wsA

Gets the app bundle path for an iOS physical device application using a workspace. IMPORTANT: Requires workspacePath and scheme. Example: get_ios_dev_app_path_ws({ workspacePath: '/path/to/workspace', scheme: 'MyScheme' })

Inputs: workspacePath (required), scheme (required), configuration.

get_mac_app_path_projA

Gets the app bundle path for a macOS application using a project file. IMPORTANT: Requires projectPath and scheme. Example: get_mac_app_path_proj({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme' })

Inputs: projectPath (required), scheme (required), configuration, arch.

get_mac_app_path_wsB

Gets the app bundle path for a macOS application using a workspace. IMPORTANT: Requires workspacePath and scheme. Example: get_mac_app_path_ws({ workspacePath: '/path/to/workspace', scheme: 'MyScheme' })

Inputs: workspacePath (required), scheme (required), configuration, arch.

get_mac_bundle_idA

Extracts the bundle identifier from a macOS app bundle (.app). IMPORTANT: You MUST provide the appPath parameter. Example: get_mac_bundle_id({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_get_macos_bundle_id.

Inputs: appPath (required).

get_sim_app_path_id_projA

Gets the app bundle path for a simulator by UUID using a project file. IMPORTANT: Requires projectPath, scheme, platform, and simulatorId. Example: get_sim_app_path_id_proj({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme', platform: 'iOS Simulator', simulatorId: 'SIMULATOR_UUID' })

Inputs: projectPath (required), scheme (required), platform (required), simulatorId (required), +2 more.

get_sim_app_path_id_wsA

Gets the app bundle path for a simulator by UUID using a workspace. IMPORTANT: Requires workspacePath, scheme, platform, and simulatorId. Example: get_sim_app_path_id_ws({ workspacePath: '/path/to/workspace', scheme: 'MyScheme', platform: 'iOS Simulator', simulatorId: 'SIMULATOR_UUID' })

Inputs: workspacePath (required), scheme (required), platform (required), simulatorId (required), +2 more.

get_sim_app_path_name_projB

Gets the app bundle path for a simulator by name using a project file. IMPORTANT: Requires projectPath, scheme, platform, and simulatorName. Example: get_sim_app_path_name_proj({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme', platform: 'iOS Simulator', simulatorName: 'iPhone 16' })

Inputs: projectPath (required), scheme (required), platform (required), simulatorName (required), +2 more.

get_sim_app_path_name_wsB

Gets the app bundle path for a simulator by name using a workspace. IMPORTANT: Requires workspacePath, scheme, platform, and simulatorName. Example: get_sim_app_path_name_ws({ workspacePath: '/path/to/workspace', scheme: 'MyScheme', platform: 'iOS Simulator', simulatorName: 'iPhone 16' })

Inputs: workspacePath (required), scheme (required), platform (required), simulatorName (required), +2 more.

install_app_simA

Installs an app in an iOS simulator. IMPORTANT: You MUST provide both the simulatorUuid and appPath parameters. Example: install_app_sim({ simulatorUuid: 'YOUR_UUID_HERE', appPath: '/path/to/your/app.app' })

Inputs: simulatorUuid (required), appPath (required).

launch_app_logs_simC

Launches an app in an iOS simulator and captures its logs.

Inputs: simulatorUuid (required), bundleId (required), args.

launch_app_simA

Launches an app in an iOS simulator. IMPORTANT: You MUST provide both the simulatorUuid and bundleId parameters.

Note: You must install the app in the simulator before launching. The typical workflow is: build → install → launch. Example: launch_app_sim({ simulatorUuid: 'YOUR_UUID_HERE', bundleId: 'com.example.MyApp' })

Inputs: simulatorUuid (required), bundleId (required), args.

launch_mac_appB

Launches a macOS application. IMPORTANT: You MUST provide the appPath parameter. Example: launch_mac_app({ appPath: '/path/to/your/app.app' }) Note: In some environments, this tool may be prefixed as mcp0_launch_macos_app.

Inputs: appPath (required), args.

list_schems_projB

Lists available schemes in the project file. IMPORTANT: Requires projectPath. Example: list_schems_proj({ projectPath: '/path/to/MyProject.xcodeproj' })

Inputs: projectPath (required).

list_schems_wsB

Lists available schemes in the workspace. IMPORTANT: Requires workspacePath. Example: list_schems_ws({ workspacePath: '/path/to/MyProject.xcworkspace' })

Inputs: workspacePath (required).

list_simsB

Lists available iOS simulators with their UUIDs.

Inputs: enabled (required).

open_simC

Opens the iOS Simulator app.

Inputs: enabled (required).

reset_network_conditionC

Resets network conditions to default in the simulator.

Inputs: simulatorUuid (required).

reset_simulator_locationC

Resets the simulator's location to default.

Inputs: simulatorUuid (required).

scaffold_ios_projectB

Scaffold a new iOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper iOS configuration.

Inputs: projectName (required), outputPath (required), bundleIdentifier, displayName, +7 more.

scaffold_macos_projectB

Scaffold a new macOS project from templates. Creates a modern Xcode project with workspace structure, SPM package for features, and proper macOS configuration.

Inputs: projectName (required), outputPath (required), bundleIdentifier, displayName, +4 more.

screenshotB

Captures screenshot for visual verification. For UI coordinates, use describe_ui instead (don't determine coordinates from screenshots).

Inputs: simulatorUuid (required).

set_network_conditionC

Simulates different network conditions (e.g., wifi, 3g, edge, high-latency, dsl, 100%loss, 3g-lossy, very-lossy) in the simulator.

Inputs: simulatorUuid (required), profile (required).

set_sim_appearanceB

Sets the appearance mode (dark/light) of an iOS simulator.

Inputs: simulatorUuid (required), mode (required).

set_simulator_locationC

Sets a custom GPS location for the simulator.

Inputs: simulatorUuid (required), latitude (required), longitude (required).

show_build_set_projB

Shows build settings from a project file using xcodebuild. IMPORTANT: Requires projectPath and scheme. Example: show_build_set_proj({ projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyScheme' })

Inputs: projectPath (required), scheme (required).

show_build_set_wsA

Shows build settings from a workspace using xcodebuild. IMPORTANT: Requires workspacePath and scheme. Example: show_build_set_ws({ workspacePath: '/path/to/MyProject.xcworkspace', scheme: 'MyScheme' })

Inputs: workspacePath (required), scheme (required).

start_sim_log_capA

Starts capturing logs from a specified simulator. Returns a session ID. By default, captures only structured logs.

Inputs: simulatorUuid (required), bundleId (required), captureConsole.

stop_sim_log_capA

Stops an active simulator log capture session and returns the captured logs.

Inputs: logSessionId (required).

swift_package_buildC

Builds a Swift Package with swift build

Inputs: packagePath (required), targetName, configuration, architectures, +1 more.

swift_package_cleanC

Cleans Swift Package build artifacts and derived data

Inputs: packagePath (required).

swift_package_listB

Lists currently running Swift Package processes

Inputs: no named parameters.

swift_package_runB

Runs an executable target from a Swift Package with swift run

Inputs: packagePath (required), executableName, arguments, configuration, +3 more.

swift_package_stopA

Stops a running Swift Package executable started with swift_package_run

Inputs: pid (required).

swift_package_testC

Runs tests for a Swift Package with swift test

Inputs: packagePath (required), testProduct, filter, configuration, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 54 tools

    Disambiguation3/5

    The tools have overlapping purposes due to excessive specialization, such as multiple build tools for iOS simulators with minor variations (by UUID vs. name, project vs. workspace). While descriptions clarify parameters, the sheer number of similar tools creates ambiguity and increases the risk of misselection, as agents must navigate many near-identical options.

    Naming Consistency4/5

    Tool names follow a consistent snake_case pattern with clear verb_noun structures, such as 'build_ios_dev_proj' or 'get_sim_app_path_id_ws'. However, minor inconsistencies exist, like 'boot_sim' using a shorter form compared to others, and some tools like 'scaffold_ios_project' deviate slightly in word order, but overall the naming is predictable and readable.

    Tool Count2/5

    With 54 tools, the count is excessive for the domain of iOS/macOS development and testing. This bloats the tool surface, making it cumbersome for agents to navigate and increasing cognitive load. A more streamlined set with fewer, more generalized tools would be more appropriate and user-friendly.

    Completeness5/5

    The tool set comprehensively covers the iOS/macOS development lifecycle, including project scaffolding, building, cleaning, running, simulator management, logging, and Swift package operations. There are no obvious gaps; agents can perform end-to-end workflows from creation to testing and deployment without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers