Skip to main content
Glama
Sign In
deenesjakoruzh

XcodeBuildMCP

by cameroncooke
npmGitHub
TypeScript
MIT License
866
1,062
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Provides tools for iOS simulator management including listing simulators, booting them, installing apps, launching apps, capturing logs, automating UI interactions, and taking screenshots.

  • Supports building and running applications on macOS, including app launching and bundle ID extraction for macOS applications.

  • Integrates with Sentry for error monitoring and diagnostics to track issues, crashes, and unexpected errors, with options to disable this functionality.

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

Table of contents

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.

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)

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
  • mise

One-line setup with mise

To install mise:

# macOS (Homebrew) brew install mise # Other installation methods # See https://mise.jdx.dev/getting-started.html

For more information about mise, visit the official documentation.

Configure MCP clients

Configure your MCP client (Windsurf, Cursor, Claude Desktop, etc.) to use the XcodeBuildMCP server by ammending your client application's MCP configuration, changing the version number to match the version you wish to use:

{ "mcpServers": { "XcodeBuildMCP": { "command": "mise", "args": [ "x", "npm:xcodebuildmcp@1.4.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.

One click to install in VS Code

Enabling UI Automation (beta)

For UI automation features (tap, swipe, screenshot, etc.), you'll need to install Facebook's idb_companion:

brew tap facebook/fb brew install idb-companion

The idb client is also required but XcodeBuildMCP attempts to install it for you. If you find that the UI automation features are still not available you can install the client manually using the following command (assumes you have Python installed):

pipx install fb-idb==1.1.7

Important

Please note that UI automation features are currently in beta so there might be some rough edges. If you encounter any issues, please report them in the issue tracker.

Note

Displaying images in tool responses and embedding them in chat context may not be supported by all MCP Clients; it's currently known to be supported in Cursor.

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": "mise", "args": [ "x", "npm:xcodebuildmcp@1.4.0", "--", "xcodebuildmcp" ], "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 the issue 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 mise
# Run the diagnostic tool using mise mise x npm:xcodebuildmcp@1.4.0 -- xcodebuildmcp-diagnostic
Using with npx
# Run the diagnostic tool using npx npx xcodebuildmcp@1.4.0 xcodebuildmcp-diagnostic

The diagnostic tool will output comprehensive information about:

  • System and Node.js environment
  • Xcode installation and configuration
  • Required dependencies (xcodebuild, idb, 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": "mise", "args": [ "x", "npm:xcodebuildmcp@1.4.0", "--", "xcodebuildmcp" ], "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": "mise", "args": [ "x", "npm:xcodebuildmcp@1.4.0", "--", "xcodebuildmcp" ], "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.

Licence

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

MCP Server Verification

Glama.ai

MseeP.a

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

XcodeBuildMCP

  1. Overview
    1. Why?
      1. Features
        1. Xcode project management
        2. Simulator management
        3. App utilities
      2. Getting started
        1. Prerequisites
        2. One-line setup with mise
        3. Configure MCP clients
        4. Enabling UI Automation (beta)
      3. Incremental build support
        1. Troubleshooting
          1. Diagnostic Tool
          2. MCP Server Logs
        2. Privacy
          1. What is sent to Sentry?
          2. Opting Out of Sentry
        3. Selective tool registration
          1. Demos
            1. Autonomously fixing build errors in Cursor
            2. Utilising the new UI automation and screen capture features
            3. Building and running iOS app in Claude Desktop
          2. Contributing
            1. Licence
              1. MCP Server Verification
                1. Glama.ai
                2. MseeP.a

              Related MCP Servers

              • Xcode MCP Server

                r-huijts
                A
                security
                A
                license
                A
                quality
                Bridges Claude AI with Xcode, enabling AI-powered code assistance, project management, and automated development tasks securely on your local machine.
                Last updated -
                9
                132
                164
                TypeScript
                MIT License
                • Apple

              • mcpxcodebuild

                ShenghaiWang
                A
                security
                A
                license
                A
                quality
                🍎 Build iOS Xcode workspace/project and feed back errors to llm.
                Last updated -
                2
                45
                Python
                MIT License
                • Apple

              • Xcode MCP Server

                PolarVista
                -
                security
                F
                license
                -
                quality
                A Model Context Protocol server that enables AI assistants to build and test Xcode projects directly through a standardized interface, with capabilities for running tests, monitoring progress, and accessing logs in real-time.
                Last updated -
                29
                TypeScript

              View all related MCP servers

              New MCP Servers

              ID: 80c3zmerx6