JSPM – xcodebuildmcp@1.3.1

Package Exports

xcodebuildmcp
xcodebuildmcp/build/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (xcodebuildmcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Overview
Why?
Features
Getting started
Troubleshooting
- Diagnostic Tool
  - Using with mise
  - Using with npx
Demos
Contributing
Licence

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

Using Cursor to build, install, and launch an app on the iOS simulator while capturing logs at run-time.

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

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 18.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 adding the following configuration, changing the version number to match the version you wish to use:

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

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

[!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.

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@latest -- xcodebuildmcp-diagnostic

Using with npx

# Run the diagnostic tool using npx
npx xcodebuildmcp@latest 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.

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 Code

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.

xcodebuildmcp