엑스코드빌드MCP

AI 어시스턴트 및 기타 MCP 클라이언트와 통합하기 위한 Xcode 관련 도구를 제공하는 MCP(Model Context Protocol) 서버입니다.

개요

이 프로젝트는 Xcode 작업을 AI 에이전트가 MCP 프로토콜을 통해 호출할 수 있는 도구로 제공하는 MCP 서버를 구현합니다. 에이전트 기반 개발 워크플로에 최적화된 표준화된 인터페이스를 통해 Xcode 프로젝트와의 프로그래밍 방식 상호작용을 지원합니다.

왜?

XcodeBuild MCP 도구는 AI 에이전트와 Xcode 프로젝트 간의 상호작용을 간소화하고 표준화하기 위해 주로 사용됩니다. 일반적인 Xcode 작업을 위한 전용 도구를 제공함으로써 수동 또는 잘못된 명령줄 호출에 대한 의존성을 제거합니다.

이를 통해 안정적이고 효율적인 개발 프로세스가 보장되어 에이전트가 구성 오류의 위험을 줄이는 동시에 Xcode의 기능을 원활하게 활용할 수 있습니다.

중요한 점은, 이 MCP를 통해 AI 에이전트는 프로젝트를 빌드하고, 오류를 검사하고, 자율적으로 반복 작업을 수행하여 코드 변경 사항을 독립적으로 검증할 수 있다는 것입니다. Sweetpad와 같은 사용자 중심 도구와 달리, XcodeBuild MCP는 에이전트가 이러한 워크플로를 효과적으로 자동화할 수 있도록 지원합니다.

특징

XcodeBuildMCP 서버는 다음과 같은 도구 기능을 제공합니다.

Xcode 프로젝트 관리

프로젝트 검색 : Xcode 프로젝트 및 작업 공간 검색
빌드 작업 : macOS, iOS 시뮬레이터 및 iOS 기기 대상을 위한 플랫폼별 빌드 도구
프로젝트 정보 : Xcode 프로젝트 및 작업 공간에 대한 스키마를 나열하고 빌드 설정을 표시하는 도구
Clean Operations : xcodebuild의 기본 clean 작업을 사용하여 빌드 제품을 정리합니다.
증분 빌드 지원 : 증분 빌드 지원을 사용하여 매우 빠른 빌드(실험적, 옵트인 필요)

시뮬레이터 관리

시뮬레이터 제어 : iOS 시뮬레이터 나열, 부팅 및 열기
앱 배포 : iOS 시뮬레이터에 앱 설치 및 실행
로그 캡처 : 시뮬레이터에서 런타임 로그 캡처
UI 자동화 : 시뮬레이터 UI 요소와 상호 작용(베타)
스크린샷 : 시뮬레이터에서 스크린샷 캡처(베타)

앱 유틸리티

번들 ID 추출 : iOS 및 macOS 앱 번들에서 번들 식별자 추출
앱 실행 : 시뮬레이터와 macOS 모두에서 빌드된 애플리케이션 실행

시작하기

필수 조건

macOS 14.5 이상
Xcode 16.x 이상
미제

mise를 사용한 한 줄 설정

mise를 설치하려면:

지엑스피1

mise에 대한 자세한 내용은 공식 문서를 참조하세요.

MCP 클라이언트 구성

XcodeBuildMCP 서버를 사용하도록 MCP 클라이언트(Windsurf, Cursor, Claude Desktop 등)를 구성하려면 클라이언트 애플리케이션의 MCP 구성을 수정하고, 사용하려는 버전과 일치하도록 버전 번호를 변경합니다.

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

[!NOTE] mise를 사용할 때 @latest 태그를 사용하지 마세요. mise가 패키지를 캐시하고 자동으로 최신 버전으로 업데이트하지 않을 수 있습니다. 대신 명시적인 버전 번호를 사용하는 것이 좋습니다.

[!중요] XcodeBuildMCP는 xcodebuild에 매크로 유효성 검사를 건너뛰도록 요청합니다. 이는 Swift 매크로를 사용하는 프로젝트를 빌드할 때 오류를 방지하기 위한 것입니다.

VS Code에 한 번의 클릭으로 설치

UI 자동화 활성화(베타)

UI 자동화 기능(탭, 스와이프, 스크린샷 등)을 사용하려면 Facebook의 idb_companion을 설치해야 합니다.

brew tap facebook/fb
brew install idb-companion

idb 클라이언트도 필요하지만 XcodeBuildMCP가 자동으로 설치를 시도합니다. UI 자동화 기능을 여전히 사용할 수 없는 경우 다음 명령을 사용하여 클라이언트를 수동으로 설치할 수 있습니다(Python이 설치되어 있다고 가정).

pipx install fb-idb==1.1.7

[!중요] UI 자동화 기능은 현재 베타 버전이므로 약간의 버그가 있을 수 있습니다. 문제가 발생하면 이슈 트래커를 통해 신고해 주세요.

[!NOTE] 도구 응답에 이미지를 표시하고 채팅 컨텍스트에 포함하는 기능은 모든 MCP 클라이언트에서 지원되지 않을 수 있습니다. 현재 Cursor에서는 지원되는 것으로 알려져 있습니다.

증분 빌드 지원

XcodeBuildMCP에는 증분 빌드에 대한 실험적 지원이 포함되어 있습니다. 이 기능은 기본적으로 비활성화되어 있으며, INCREMENTAL_BUILDS_ENABLED 환경 변수를 true 로 설정하여 활성화할 수 있습니다.

증분 빌드를 활성화하려면 INCREMENTAL_BUILDS_ENABLED 환경 변수를 true 로 설정합니다.

MCP 클라이언트 구성 예:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "INCREMENTAL_BUILDS_ENABLED": "true"
      }        
    }
  }
}

[!중요] 증분 빌드 지원은 현재 매우 실험적인 단계이므로 사용자 환경에 따라 결과가 다를 수 있습니다. 문제가 발생하면 이슈 트래커 에 보고해 주세요.

문제 해결

XcodeBuildMCP에서 문제가 발생하면 진단 도구가 사용자 환경과 종속성에 대한 자세한 정보를 제공하여 문제를 식별하는 데 도움이 될 수 있습니다.

진단 도구

진단 도구는 시스템 구성을 확인하고 XcodeBuildMCP에 필요한 모든 종속성의 상태를 보고하는 독립형 유틸리티입니다. 특히 문제 보고 시 유용합니다.

mise와 함께 사용

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

npx와 함께 사용

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

진단 도구는 다음에 대한 포괄적인 정보를 출력합니다.

시스템 및 Node.js 환경
Xcode 설치 및 구성
필수 종속성(xcodebuild, idb 등)
XcodeBuildMCP에 영향을 미치는 환경 변수
기능 가용성 상태

GitHub에서 문제를 보고할 때는 문제 해결에 도움이 되도록 진단 도구의 전체 출력을 포함하세요.

MCP 서버 로그

MCP 서버의 로그 메시지에 접근하여 문제를 파악하는 것이 도움이 될 수 있습니다. 로그는 클라이언트 애플리케이션(예: Cursor)에서 캡처됩니다.

커서:

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

MCP 클라이언트에 로그 파일이 없는 경우 MCP Inspector 도구를 사용하여 서버를 직접 실행할 수 있습니다. 자세한 내용은 디버깅을 참조하세요. MCP 도구를 실행하면 모든 로그 메시지가 오류 창에 출력되므로 문제 진단에 도움이 될 수 있습니다.

은둔

이 프로젝트에서는 Sentry를 사용하여 오류 모니터링 및 진단을 수행합니다. Sentry는 문제, 충돌 및 예기치 않은 오류를 추적하여 XcodeBuildMCP의 안정성과 신뢰성을 향상시키는 데 도움이 됩니다.

Sentry에 무엇이 전송되나요?

기본적으로 오류 수준 로그와 진단 정보만 Sentry로 전송됩니다.
오류 로그에는 오류 메시지, 스택 추적, 그리고 경우에 따라 파일 경로나 프로젝트 이름 등의 세부 정보가 포함될 수 있습니다. 이 저장소의 소스를 검토하면 로깅된 내용을 정확히 확인할 수 있습니다.

센트리 옵트아웃

Sentry에 오류 로그를 보내고 싶지 않으면 환경 변수 SENTRY_DISABLED=true 설정하여 옵트아웃할 수 있습니다.

MCP 클라이언트 구성 예:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "SENTRY_DISABLED": "true"
      }        
    }
  }
}

선택적 도구 등록

기본적으로 모든 도구가 활성화되어 있지만, 일부 클라이언트의 경우 클라이언트로 전송되는 컨텍스트의 양을 줄이기 위해 특정 도구만 활성화하는 것이 유용할 수 있습니다. 이는 클라이언트 MCP 구성에서 특정 환경 변수를 설정하여 구현할 수 있습니다.

하나 이상의 도구 또는 도구 그룹을 활성화하면 다른 모든 도구는 비활성화됩니다. 예를 들어, 시뮬레이터 관련 도구만 활성화하려면 환경 변수를 XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true 로 설정하면 됩니다. 이렇게 하면 시뮬레이터에서 빌드, 실행 및 디버깅을 위한 도구만 노출됩니다.

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.4.0",
        "--",
        "xcodebuildmcp"
      ],
      "env": {
        "XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true"
      }        
    }
  }
}

사용 가능한 도구 목록과 이를 활성화하는 방법에 대한 자세한 지침은 TOOL_OPTIONS.md 파일에서 확인할 수 있습니다.

시민

Cursor에서 빌드 오류를 자율적으로 수정

새로운 UI 자동화 및 화면 캡처 기능 활용

Claude Desktop에서 iOS 앱 빌드 및 실행

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

기여하다

기여를 환영합니다! XcodeBuildMCP 개선에 도움을 주실 수 있는 방법은 다음과 같습니다.

로컬 환경을 구성하고 프로젝트에 기여하는 방법에 대한 자세한 내용은 CONTRIBUTING 문서를 참조하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

Integrations

목차

개요

왜?

특징