Xcodebuildmcp

🚀 XcodeBuildMCP: A Model Context Protocol (MCP) Server

XcodeBuildMCP is an MCP server that offers Xcode-related tools for seamless integration with AI assistants and other MCP clients. It simplifies and standardizes interactions with Xcode projects, enabling efficient agent-driven development workflows.

🚀 Quick Start

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:

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"
      ]
    }
  }
}

⚠️ Important 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 Note Please note that XcodeBuildMCP will request xcodebuild to skip macro validation. This is to avoid errors when building projects that use Swift Macros.

✨ Features

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

🔧 Technical Details

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:

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

⚠️ Important Note Please note that incremental builds support is currently highly experimental and your mileage may vary. Please report any issues you encounter to the issue tracker.

📚 Documentation

Troubleshooting

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:

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.

{
  "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.

{
  "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

Utilising the new UI automation and screen capture features

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.

📄 License

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

MCP Server Verification

Glama.ai

MseeP.a