phantom-mcp

Claude Code가 iOS 시뮬레이터, Android 에뮬레이터 및 실제 기기를 보고 제어할 수 있게 해주는 MCP 서버입니다. 터미널을 떠나지 않고도 모바일 앱을 테스트할 수 있는 22개의 도구를 제공합니다.

Claude는 iOS와 Android에서 자동으로 스크린샷 촬영, 화면 읽기, 탭, 스크롤, 필드 입력, 어설션 확인, 비디오 녹화를 수행할 수 있습니다.

테스트 세션마다 스크린샷이 포함된 테스트 보고서가 자동으로 생성됩니다.

아키텍처

Claude Code
    | MCP protocol (stdio)
    v
Phantom (Node.js TypeScript)
    |                       |
    v                       v
iOS                      Android
  xcrun simctl             ADB
  WebDriverAgent           UIAutomator
  (localhost:8100)         (adb shell)
    |                       |
    v                       v
Simulateur / iPhone    Emulateur / Device

필수 조건

도구	용도	확인 방법
macOS 13+	전체	-
Xcode 15+	iOS	`xcode-select -p`
Node.js 18+	전체	`node --version`
Appium 3+	iOS (WDA)	`appium --version`
xcuitest driver	iOS (WDA)	`appium driver list --installed`
Android SDK	Android	`adb version`

설치

옵션 A — npm (권장)

# 1. Installer le package
npm install -g phantom-mcp

# 2. Installer Appium + driver iOS
npm install -g appium
appium driver install xcuitest

# 3. Enregistrer dans Claude Code
claude mcp add -s user phantom -- npx phantom-mcp

옵션 B — 소스에서 설치

git clone https://github.com/nthimpulse/phantom-mcp.git
cd phantom-mcp
npm install
npm run build
claude mcp add -s user phantom -- node "$(pwd)/build/index.js"

22개의 도구

기기 관리

도구	설명
`list_devices`	모든 기기 나열 (iOS 시뮬레이터 + Android 에뮬레이터 + 실제 기기)
`set_device`	활성 기기 선택. 꺼져 있을 경우 자동 부팅

관찰

도구	설명
`screenshot`	활성 기기의 화면 캡처
`get_ui_tree`	각 요소에 대한 인덱스 [N]이 포함된 접근성 트리
`wait_for_element`	요소가 나타날 때까지 대기 (타임아웃 포함)
`scroll_until_visible`	요소를 찾을 때까지 스크롤

어설션

도구	설명
`assert_visible`	텍스트가 화면에 있는지 확인
`assert_not_visible`	텍스트가 화면에 없는지 확인

상호작용

도구	설명
`tap`	탭 (인덱스, 좌표 또는 텍스트 기준)
`long_press`	길게 누르기 (컨텍스트 메뉴)
`type_text`	텍스트 입력 (지우기 옵션 포함)
`swipe`	스와이프 (위/아래/왼쪽/오른쪽)

탐색

도구	설명
`deep_link`	URL / 딥링크 열기

기기 동작

도구	설명
`shake`	흔들기 시뮬레이션
`rotate`	방향 변경 (세로/가로)
`video_record`	비디오 녹화 시작/중지

앱 수명 주기

도구	설명
`launch_app`	번들 ID / 패키지 이름으로 앱 실행
`kill_app`	앱 종료

분석 및 자동화 (Tier 3)

도구	설명
`accessibility_audit`	접근성 감사: 누락된 레이블, 너무 작은 탭 대상, alt 텍스트가 없는 이미지
`test_report`	자동 테스트 보고서: start로 추적 시작, end로 마크다운 생성. 모든 작업이 자동으로 기록됨
`visual_diff`	두 스크린샷을 픽셀 단위로 비교하여 시각적 회귀 감지
`multi_device`	한 번의 명령으로 여러 기기에서 동일한 작업 실행

자동 작동 방식

기기 선택

Phantom은 기기를 자동으로 부팅하지 않습니다. 선택을 요청합니다:

활성 기기가 1개뿐이면 자동으로 사용합니다.
여러 개일 경우 set_device를 통해 선택을 요청합니다.
없을 경우 사용 가능한 기기 목록을 보여줍니다.

WDA 자동 실행 (iOS)

WebDriverAgent는 필요한 iOS 도구가 처음 호출될 때 자동으로 실행됩니다. 첫 실행 시 약 60-90초(Xcode 빌드)가 소요되며, 이후에는 즉시 실행됩니다.

ADB 다중 기기 (Android)

모든 ADB 명령은 -s <serial>을 통해 선택된 기기를 대상으로 합니다. 다중 기기 혼동이 없습니다.

텍스트 입력 (AZERTY 호환)

가상 키보드 대신 pbcopy + Cmd+V (붙여넣기)를 사용합니다. 즉각적이며 모든 키보드 레이아웃(AZERTY, QWERTY 등)에서 작동합니다.

자동 테스트 보고서

모든 작업(탭, 입력, 스와이프, 어설션 등)은 스크린샷과 함께 자동으로 기록됩니다. 테스트가 끝나면 /tmp/phantom-report-xxx/에 마크다운 보고서가 생성됩니다.

보안

모든 시스템 명령은 execFile을 통과합니다 (쉘 사용 안 함)
번들 ID, UDID, 패키지 이름, AVD 이름, URL 등 정규식으로 입력값 검증
iOS 술어 이스케이프 처리 (인젝션 방지)
Android 텍스트는 기기 쉘을 위해 이스케이프 처리
as any 사용 금지, exec() 쉘 사용 금지

설정

선택적 환경 변수:

PHANTOM_WDA_PATH — WebDriverAgent 경로 (기본값: ~/.appium/...)
PHANTOM_WDA_URL — WDA URL (기본값: http://localhost:8100)

문제 해결

WDA 무한 충돌

MobAI 또는 다른 도구가 8100 포트를 사용 중입니다.

lsof -i :8100
pkill -f "MobAI"

"사용 가능한 기기 없음"

xcrun simctl list devices available   # iOS
adb devices -l                        # Android

WDA가 시작되지 않음

cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
xcodebuild -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination "platform=iOS Simulator,name=iPhone 17 Pro" \
  test

ADB를 찾을 수 없음

ls ~/Library/Android/sdk/platform-tools/adb

프로젝트 구조

phantom/
  src/
    index.ts                Point d'entree MCP (22 tools)
    platforms/
      types.ts              Interfaces communes
      ios/
        simctl.ts            Wrapper xcrun simctl
        wda.ts               Client WDA + auto-launch
      android/
        adb.ts               Wrapper ADB complet
    tools/                   22 tools (19 fichiers)
    utils/
      device-manager.ts      Detection + routing multi-device
      xml.ts                 Parser XML partage
  docs/
    README.md               Ce fichier
    TUTORIAL.md             Tuto pas-a-pas
    FLOWS.md                Exemples de flows de test

phantom-mcp

phantom-mcp

아키텍처

필수 조건

설치

옵션 A — npm (권장)

옵션 B — 소스에서 설치

22개의 도구

기기 관리

관찰

어설션

상호작용

탐색

기기 동작

앱 수명 주기

분석 및 자동화 (Tier 3)

자동 작동 방식

기기 선택

WDA 자동 실행 (iOS)

ADB 다중 기기 (Android)

텍스트 입력 (AZERTY 호환)

자동 테스트 보고서

보안

설정

문제 해결

WDA 무한 충돌

"사용 가능한 기기 없음"

WDA가 시작되지 않음

ADB를 찾을 수 없음

프로젝트 구조

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API