atom2ueki/mcp-server-ios-simulator

appium-ios-simulator를 기반으로 구축되었으며 MCP TypeScript SDK를 활용하여 iOS 시뮬레이터(iOS simulators)를 위한 Model Context Protocol (MCP)을 구현하는 서버입니다.

이 프로젝트는 iOS 시뮬레이터와 Model Context Protocol (MCP) 사이의 브릿지(bridge)를 제공하여, iOS 시뮬레이터 인스턴스와의 표준화된 통신을 가능하게 합니다. 이를 통해 다양한 환경에서 일관된 인터페이스를 위해 MCP 프로토콜을 활용하면서 iOS 시뮬레이터를 프로그래밍 방식으로 제어할 수 있습니다. 이 서버는 전송 메커니즘(transport mechanism)으로 stdio를 사용하여 Claude Desktop 및 기타 MCP 호환 클라이언트와의 통합에 이상적입니다.

Claude AI Desktop을 사용하여 iOS 시뮬레이터를 부팅하는 방법을 보여주는 데모

서버는 세 가지 주요 구성 요소로 이루어져 있습니다:

🔄 시뮬레이터 관리 계층 (Simulator Management Layer)- iOS 시뮬레이터의 생명주기(lifecycle) 및 상호작용을 처리합니다
🔌 MCP 프로토콜 구현 (MCP Protocol Implementation)- stdio 전송 방식을 사용하는 TypeScript SDK를 사용하여 Model Context Protocol (MCP)을 구현합니다
📊 로거 구성 요소 (Logger Component)- stdio 전송을 방해하지 않고 파일 기반 로깅(file-based logging)을 제공합니다

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP Protocol │ │ Stdio │ │ Simulator │
│ Implementation │◄────┤ Transport │◄────┤ Management │
...

• 🚀 iOS 시뮬레이터 인스턴스 시작, 중지 및 관리

• 🔌 시뮬레이터 부팅 및 종료

• 📲 시뮬레이터에 애플리케이션 설치 및 실행

• 📸 시뮬레이터 화면 스크린샷 촬영

• 👆 좌표 기반 탭(taps) 수행

• 🔄 다중 동시 시뮬레이터 세션 지원

• 📝 콘솔 출력 없이 포괄적인 파일 기반 로깅 제공

• 🛡️ 오류 복구 능력이 있는 운영 (Error-resilient operation)

• 🟢 Node.js (v16 이상)

• 🍎 macOS (iOS 시뮬레이터를 위해 필수)

• 🛠️ iOS 시뮬레이터가 설치된 Xcode

• 📜 TypeScript 4.5+

Smithery를 통해 Claude Desktop용 iOS Simulator Control Server를 자동으로 설치하려면:

npx -y @smithery/cli install @atom2ueki/mcp-server-ios-simulator --client claude

# 저장소 클론 (Clone the repository)
git clone https://github.com/atom2ueki/mcp-server-ios-simulator.git
cd mcp-server-ios-simulator
...

Glama MCP 디렉토리 및 기타 컨테이너 호스트를 위해 서버를 패키징할 수 있도록 Dockerfile이 제공됩니다.

docker build -t mcp-server-ios-simulator .
docker run --rm -i mcp-server-ios-simulator

참고: iOS 시뮬레이터(simulators)는 macOS에서만 실행되므로, Linux 컨테이너는 MCP 프로세스를 호스팅하고 stdio를 통해 응답할 수는 있지만 실제 시뮬레이터를 구동할 수는 없습니다. 이 컨테이너는 이식성 확인 및 macOS 호스트로 브릿지(bridge)되는 원격 MCP 환경을 위해 의도되었습니다.

설정은 src/config.ts 파일을 통해 관리됩니다:

const config = {
simulator: {
defaultDevice: process.env.SIMULATOR_DEFAULT_DEVICE || 'iPhone 16',
...

환경 변수를 설정하여 이러한 설정을 사용자 정의할 수 있습니다:

SIMULATOR_DEFAULT_DEVICE=iPhone 16
SIMULATOR_DEFAULT_OS=18.2
SIMULATOR_TIMEOUT=30000

# 프로젝트 빌드
npm run build
# 서버 시작
...

서버는 iOS 시뮬레이터를 제어하기 위한 두 가지 별개의 접근 방식을 제공합니다:

이 도구들은 시뮬레이터의 UDID와 직접 작동하며 세션(sessions)을 유지 관리할 필요가 없습니다:

• 📋 list-available-simulators: UDID를 포함하여 사용 가능한 모든 시뮬레이터 목록 표시
• ▶️ boot-simulator-by-udid: UDID를 사용하여 시뮬레이터를 직접 부팅
• ⏹️ shutdown-simulator-by-udid: UDID를 사용하여 시뮬레이터를 직접 종료
• 📊 list-booted-simulators: 현재 부팅된 모든 시뮬레이터 목록 표시

이 접근 방식을 사용하는 경우: 시뮬레이터를 직접 부팅, 사용 및 종료하기만 하면 될 때.

이 도구들은 사용자 정의 세션 ID로 시뮬레이터를 추적하는 세션 레이어(session layer)를 사용합니다:

• 📋 list-simulator-sessions: 모든 활성 시뮬레이터 세션 목록 표시
• ➕ create-simulator-session: 새로운 시뮬레이터 세션 생성
• ❌ terminate-simulator-session: 세션 종료 (시뮬레이터를 종료하고 정리함)
• 🔄 create-and-boot-simulator: 새로운 시뮬레이터 세션을 생성하고 부팅
• ▶️ boot-simulator: 기존 세션을 위해 시뮬레이터 부팅
• ⏹️ shutdown-simulator: 기존 세션을 위해 시뮬레이터 종료

다음과 같은 경우에 이 방식을 사용하세요: 시뮬레이터 메타데이터를 추적해야 하거나, 사용자 정의 ID로 시뮬레이터를 참조해야 하거나, 더 고급 관리 기능이 필요한 경우.

• 📥 install-app: 시뮬레이터에 애플리케이션 설치
• 🚀 launch-app: 시뮬레이터에서 애플리케이션 실행
• 🛑 terminate-app: 시뮬레이터에서 실행 중인 애플리케이션 종료
• 📷 take-screenshot: 시뮬레이터 화면 스크린샷 촬영
• 👆 tap-coordinate: 지정된 좌표에서 탭(tap) 수행

Claude Desktop이 이 서버를 MCP 도구로 사용하도록 설정하려면:

• Claude Desktop을 엽니다.
• Settings > Advanced로 이동합니다.
• "MCP Servers" 섹션에 다음 설정을 추가합니다:

{ "mcpServers": { "simulator": { "command": "node", "args": [ "/path/to/your/mcp-server-ios-simulator/dist/index.js" ] } } }

• /path/to/your를 이 리포지토리가 설치된 실제 경로로 교체합니다.
• 설정을 저장하고 Claude Desktop을 재시작합니다.

제공된 도구들을 사용하여 Claude Desktop에서 iOS 시뮬레이터를 직접 제어하세요:

직접 UDID 접근 방식 (권장):

• 먼저, Claude에게 사용 가능한 시뮬레이터 목록을 요청하세요:
  "Show me all available iOS simulators" (사용 가능한 모든 iOS 시뮬레이터를 보여줘)
• 그런 다음 UDID를 사용하여 특정 시뮬레이터를 부팅하세요:
  "Boot the iOS simulator with UDID 5272EA61-5796-4372-86FE-3B33831D5CC1" (UDID 5272EA61-5796-4372-86FE-3B33831D5CC1인 iOS 시뮬레이터를 부팅해줘)
• 작업이 끝나면 동일한 UDID를 사용하여 종료하세요:
  "Shut down the simulator with UDID 5272EA61-5796-4372-86FE-3B33831D5CC1" (UDID 5272EA61-5796-4372-86FE-3B33831D5CC1인 시뮬레이터를 종료해줘)

직접 UDID 접근 방식은 대부분의 사용 사례에서 더 간단하고 신뢰할 수 있습니다.

세션 기반 접근 방식 (고급):
세션 추적(session tracking)의 고급 기능이 필요한 경우에만 이 방식을 사용하세요:
"Create a new simulator session for iPhone 16 Pro with iOS 18.2" (iOS 18.2가 설치된 iPhone 16 Pro를 위한 새로운 시뮬레이터 세션을 생성해줘)
"Boot the simulator for session abc-123" (세션 abc-123을 위한 시뮬레이터를 부팅해줘)
"Take a screenshot of the simulator for session abc-123" (세션 abc-123의 시뮬레이터 스크린샷을 찍어줘)
"Terminate the simulator session abc-123" (시뮬레이터 세션 abc-123을 종료해줘)

src/
├── simulator/ # 시뮬레이터 관리 레이어 (Simulator management layer)
├── mcp/ # MCP 프로토콜 구현 (MCP protocol implementation)
...

# 개발 의존성 설치
npm install
# TypeScript 컴파일러 실행
...

이 프로젝트는 MIT 라이선스(MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

• 📱 iOS 시뮬레이터 상호작용 기능을 제공하기 위한 appium-ios-simulator
• 🔌 프로토콜 사양 및 TypeScript SDK를 위한 Model Context Protocol (MCP)