📱 iOS 시뮬레이터용 MCP 서버

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

📋 개요

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

Related MCP server: Simulator MCP

🎬 데모

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

🏗️ 아키텍처

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

1. 🔄 시뮬레이터 관리 계층 - iOS 시뮬레이터 수명 주기 및 상호 작용 처리

2. 🔌 MCP 프로토콜 구현 - stdio 전송과 함께 TypeScript SDK를 사용하여 Model Context Protocol 구현

3. 📊 로거 구성 요소 - stdio 전송을 방해하지 않으면서 파일 기반 로깅 제공

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  MCP Protocol   │     │     Stdio       │     │    Simulator    │
│  Implementation │◄────┤    Transport    │◄────┤   Management    │
│                 │     │                 │     │      Layer      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        ▲                                                ▲
        │                                                │
        ▼                                                ▼
┌─────────────────┐                             ┌─────────────────┐
│   MCP Client    │                             │  iOS Simulator  │
│  (e.g. Claude)  │                             │                 │
└─────────────────┘                             └─────────────────┘

✨ 기능

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

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

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

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

• 👆 좌표 탭 수행

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

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

• 🛡️ 오류 복구 가능한 작업

📋 사전 요구 사항

• 🟢 Node.js (v16 이상)

• 🍎 macOS (iOS 시뮬레이터에 필요)

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

• 📜 TypeScript 4.5+

🔧 설치

Smithery를 통한 설치

Smithery를 통해 Claude Desktop용 iOS 시뮬레이터 제어 서버를 자동으로 설치하려면:

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

# Install dependencies
npm install

🐳 Docker

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

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

참고: iOS 시뮬레이터는 macOS에서만 실행되므로, Linux 컨테이너는 MCP 프로세스를 호스팅하고 stdio로 응답할 수는 있지만 실제 시뮬레이터를 구동할 수는 없습니다. 이 컨테이너는 이식성 확인 및 macOS 호스트에 연결되는 원격 MCP 환경을 위한 것입니다.

⚙️ 구성

구성은 src/config.ts 파일을 통해 처리됩니다:

const config = {
  simulator: {
    defaultDevice: process.env.SIMULATOR_DEFAULT_DEVICE || 'iPhone 16',
    defaultOS: process.env.SIMULATOR_DEFAULT_OS || '18.2',
    timeout: parseInt(process.env.SIMULATOR_TIMEOUT || '30000', 10),
  }
};

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

SIMULATOR_DEFAULT_DEVICE=iPhone 16
SIMULATOR_DEFAULT_OS=18.2
SIMULATOR_TIMEOUT=30000

🚀 사용법

🔨 서버 빌드 및 시작

# Build the project
npm run build

# Start the server
npm start

🧰 MCP 도구

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

📱 직접 시뮬레이터 관리 (권장)

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

• 📋 list-available-simulators - UDID를 포함한 모든 사용 가능한 시뮬레이터 나열

• ▶️ boot-simulator-by-udid - UDID를 사용하여 시뮬레이터를 직접 부팅

• ⏹️ shutdown-simulator-by-udid - UDID를 사용하여 시뮬레이터를 직접 종료

• 📊 list-booted-simulators - 현재 부팅된 모든 시뮬레이터 나열

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

📱 세션 기반 관리 (고급)

이 도구들은 사용자 지정 세션 ID로 시뮬레이터를 추적하는 세션 계층을 사용합니다:

• 📋 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 - 지정된 좌표에서 탭 수행

🤖 Claude Desktop에서의 사용 예시

1. 이 서버를 MCP 도구로 사용하도록 Claude Desktop 구성:

   • Claude Desktop 열기

   • 설정 > 고급으로 이동

   • "MCP Servers" 섹션에 다음 구성을 추가:

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

   • /path/to/your를 이 저장소를 설치한 실제 경로로 바꿉니다.

   • 설정을 저장하고 Claude Desktop을 다시 시작합니다.

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

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

   1. 먼저 Claude에게 사용 가능한 시뮬레이터를 나열하도록 요청:

      "Show me all available iOS simulators"

   2. 그런 다음 UDID를 사용하여 특정 시뮬레이터를 부팅:

      "Boot the iOS simulator with UDID 5272EA61-5796-4372-86FE-3B33831D5CC1"

   3. 완료되면 동일한 UDID를 사용하여 종료:

      "Shut down the simulator with UDID 5272EA61-5796-4372-86FE-3B33831D5CC1"

   직접 UDID 접근 방식은 대부분의 사용 사례에서 더 간단하고 안정적입니다.

   세션 기반 접근 방식 (고급): 세션 추적의 고급 기능이 필요한 경우에만 이 접근 방식을 사용하세요:

   "Create a new simulator session for iPhone 16 Pro with iOS 18.2"
   "Boot the simulator for session abc-123"
   "Take a screenshot of the simulator for session abc-123"
   "Terminate the simulator session abc-123"

👨💻 개발

📁 프로젝트 구조

src/
├── simulator/       # Simulator management layer
├── mcp/             # MCP protocol implementation
├── bridge/          # Bridge component
├── utils/           # Utility functions including logger
├── config.ts        # Configuration handling
└── index.ts         # Entry point

🔨 프로젝트 빌드

# Install development dependencies
npm install

# Run TypeScript compiler
npm run build

📜 라이선스

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

🙏 감사의 말

• 📱 appium-ios-simulator (iOS 시뮬레이터 상호 작용 기능 제공)

• 🔌 Model Context Protocol (프로토콜 사양 및 TypeScript SDK)