xcode-studio-mcp

Xcode + iOS 시뮬레이터를 위한 통합 MCP 서버 — Claude Code, Codex, Cursor 또는 모든 MCP 클라이언트에서 iOS 앱을 빌드, 배포, 스크린샷 촬영 및 상호 작용할 수 있습니다.

Swift로 빌드되었습니다. 단일 바이너리입니다. Node/Python 런타임이 필요하지 않습니다.

License: MIT Swift 6.0+ MCP

이 프로젝트의 존재 이유

현재 AI 에이전트로 전체 iOS 개발 루프를 수행하려면 2~3개의 별도 도구가 필요합니다. xcode-studio-mcp는 이를 하나로 결합합니다:

Write code → Build → Deploy to Simulator → Screenshot → Tap/Type → Verify

도구

도구	설명
`xcode_build`	구조화된 오류 출력(파일, 행, 열, 심각도, 메시지)과 함께 Xcode 프로젝트 빌드
`xcode_run`	iOS 시뮬레이터에서 앱 빌드 및 실행
`simulator_screenshot`	시뮬레이터 화면을 PNG 이미지로 캡처
`simulator_tap`	시뮬레이터 화면의 x,y 좌표 탭
`simulator_type`	현재 포커스된 필드에 텍스트 입력
`simulator_describe`	현재 화면의 접근성 트리 가져오기 (JSON)

도구 매개변수

`xcode_build`

매개변수	필수	설명
`project_path`	예	Xcode 프로젝트 디렉토리, `.xcodeproj` 또는 `.xcworkspace` 경로
`scheme`	아니요	빌드 스킴 (생략 시 자동 감지)
`configuration`	아니요	`Debug` (기본값) 또는 `Release`
`destination`	아니요	빌드 대상 (기본값은 부팅된 시뮬레이터)

`xcode_run`

매개변수	필수	설명
`project_path`	예	Xcode 프로젝트 경로
`bundle_identifier`	예	앱 번들 ID (예: `com.example.MyApp`)
`scheme`	아니요	빌드 스킴 (자동 감지)
`simulator_udid`	아니요	대상 시뮬레이터 (기본값은 부팅된 시뮬레이터)

`simulator_screenshot`

매개변수	필수	설명
`simulator_udid`	아니요	대상 시뮬레이터 (기본값은 부팅된 시뮬레이터)

`simulator_tap`

매개변수	필수	설명
`x`	예	X 좌표
`y`	예	Y 좌표
`duration`	아니요	누르고 있는 시간(초) (길게 누르기용)
`simulator_udid`	아니요	대상 시뮬레이터

`simulator_type`

매개변수	필수	설명
`text`	예	입력할 텍스트
`simulator_udid`	아니요	대상 시뮬레이터

`simulator_describe`

매개변수	필수	설명
`simulator_udid`	아니요	대상 시뮬레이터

빠른 시작

사전 요구 사항

Xcode가 설치된 macOS

UI 상호 작용 도구(tap, type, describe) 사용 시:

brew tap facebook/fb && brew install idb-companion
pip3 install fb-idb

빌드

git clone https://github.com/kevinswint/xcode-studio-mcp.git
cd xcode-studio-mcp
swift build -c release

Claude Code 구성

Claude Code MCP 설정에 추가하세요:

{
  "mcpServers": {
    "xcode-studio-mcp": {
      "command": "/path/to/xcode-studio-mcp/.build/release/XcodeStudioMCP"
    }
  }
}

예시 워크플로우

You: Build and run my app at ~/Projects/MyApp
Claude: [calls xcode_build] Build succeeded with 0 errors
        [calls xcode_run] App launched (PID 12345)
        [calls simulator_screenshot] Here's what the app looks like...
        [calls simulator_describe] I can see a "Sign In" button and email/password fields
        [calls simulator_tap] Tapped the email field
        [calls simulator_type] Typed "test@example.com"
        [calls simulator_screenshot] Here's the current state...

아키텍처

┌─────────────────────────────┐
│     MCP Protocol Layer      │  stdio transport (Swift MCP SDK)
├─────────────────────────────┤
│   Tool Implementations      │  6 tools, structured error output
├──────────┬──────────────────┤
│ xcodebuild│  simctl  │  idb │  native process calls
│  wrapper  │  wrapper │ CLI  │
└──────────┴──────────┴──────┘

Node/Python 런타임 의존성 없이 Swift로 빌드되었습니다 (idb CLI는 UI 상호 작용 도구에만 필요합니다).

로드맵

v0.1 (현재): 핵심 빌드 + 시뮬레이터 도구
v1.0: 의미론적 UI 탐색 ("로그인 버튼 탭"), 시각적 차이 비교, Xcode 프로젝트 파일 조작, 복합 작업, SwiftUI 미리보기 캡처

기여

PR을 환영합니다. 코드베이스는 도구, 서비스, 모델로 구성된 약 750줄의 Swift 코드로 이루어져 있습니다.

라이선스

MIT

프로젝트	기능	차이점
XcodeBuildMCP	빌드 + 테스트 전용	시뮬레이터 UI 상호 작용 없음
mobile-mcp	크로스 플랫폼 시뮬레이터 UI	Xcode 빌드 지원 없음
ios-simulator-mcp	IDB를 통한 시뮬레이터	빌드 기능 없음, 모든 기능이 IDB에 의존

Xcode-Studio-MCP