Skip to main content
Glama
deenesfrjakoruzh
nthImpulse

phantom-mcp

by nthImpulse
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

phantom-mcp

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

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

Related MCP server: mobile-device-mcp

필수 조건

도구

용도

확인 방법

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"

24개의 도구

기기 관리

도구

설명

list_devices

모든 기기 나열 (iOS 시뮬레이터 + Android 에뮬레이터 + 실제 기기)

set_device

활성 기기 선택. 꺼져 있으면 자동 부팅. 기기 자동 준비 (skip_setup으로 비활성화 가능)

prepare_device

기기를 깨끗한 상태로 설정: 클립보드 지우기 / 상태 표시줄 재정의 / 키보드 닫기 / iOS QWERTY 강제 설정

관찰

도구

설명

screenshot

활성 기기의 화면 캡처

get_ui_tree

각 요소에 대한 인덱스 [N]이 포함된 접근성 트리

wait_for_element

요소가 나타날 때까지 대기 (타임아웃 포함)

scroll_until_visible

요소가 보일 때까지 스크롤

어설션

도구

설명

assert_visible

텍스트가 화면에 있는지 확인

assert_not_visible

텍스트가 화면에 없는지 확인

상호작용

도구

설명

tap

탭 (인덱스, 좌표 또는 텍스트 기준). 대상이 가려져 있으면 키보드 자동 닫기

long_press

길게 누르기 (컨텍스트 메뉴)

type_text

텍스트 입력 (지우기 옵션 및 입력 후 값 재확인을 위한 검증 옵션 포함)

swipe

스와이프 (위/아래/왼쪽/오른쪽)

dismiss_keyboard

소프트 키보드 닫기 (보이지 않으면 아무 작업도 안 함)

탐색

도구

설명

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. 활성 기기가 1개뿐이면 자동으로 사용합니다.

  2. 여러 개이면 set_device를 통해 선택을 요청합니다.

  3. 없으면 사용 가능한 기기 목록을 보여줍니다.

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)

기여하기

로컬 설정, 새 도구 추가 패턴, 명명 규칙 및 PR 워크플로우는 CONTRIBUTING.md를 참조하세요.

참조:

문제 해결

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 (24 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/                   24 tools (21 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
Install Server
A
license - permissive license
A
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • iOS Development MCP Server

    dagba
    A
    license
    -
    quality
    F
    maintenance
    An MCP server that provides comprehensive tools for managing iOS simulators, including device control, app lifecycle management, and UI automation. It enables developers to boot devices, install apps, capture screenshots, and simulate user interactions through natural language commands.
    3
    MIT

  • mobile-device-mcp

    saranshbamania
    A
    license
    A
    quality
    D
    maintenance
    MCP server that gives AI coding assistants the ability to see and interact with mobile devices. 49 tools for Android/iOS — AI-powered visual analysis (Claude + Gemini), smart tap/type by description, Flutter widget tree inspection, video recording, and test script generation. 4-tier element search with <1ms local matching. Free tier included, zero setup via npx.
    49
    79
    3
    Business Source 1.1

  • mobile-mcp

    kimkitae
    A
    license
    -
    quality
    D
    maintenance
    MCP server for cross-platform mobile automation (iOS/Android) using accessibility trees and screenshots, enabling agents to interact with apps on simulators, emulators, and physical devices.
    7
    Apache 2.0

  • open-mobile-mcp

    xzaleksey
    A
    license
    -
    quality
    D
    maintenance
    An MCP server for mobile automation that enables LLMs to interact with Android and iOS devices through screenshot, tap, swipe, log analysis, and app lifecycle management.
    24
    2
    MIT

View all related MCP servers

Related MCP Connectors

  • Appcircle MCP

    MCP server for Appcircle mobile CI/CD platform.

  • mcp

    Augments MCP Server - A comprehensive framework documentation provider for Claude Code

  • DataDoe MCP

    Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nthImpulse/phantom-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server