phantom-mcp

MCP-сервер, который позволяет Claude Code видеть и управлять iOS-симуляторами, Android-эмуляторами и реальными устройствами. 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

Предварительные требования

Установка

Вариант А — 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

Вариант Б — из исходного кода

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 инструмента

Управление устройствами

Наблюдение

Утверждения (Assertions)

Взаимодействие

Навигация

Действия с устройством

Жизненный цикл приложения

Анализ и автоматизация (Уровень 3)

Автоматическая работа

Выбор устройства

Phantom никогда не загружает устройство автоматически. Он просит вас выбрать:

1. Если активно только 1 устройство, он использует его автоматически

2. Если их несколько, он просит выбрать с помощью set_device

3. Если ни одного, он показывает список доступных устройств

Автозапуск WDA (iOS)

WebDriverAgent запускается автоматически при первом использовании инструмента iOS, которому он нужен. Первый запуск ~60-90 секунд (сборка Xcode), затем мгновенно.

ADB multi-device (Android)

Все команды ADB нацелены на устройство, выбранное через -s <serial>. Никакой путаницы при работе с несколькими устройствами.

Ввод текста (совместимость с AZERTY)

Ввод использует pbcopy + Cmd+V (вставка) вместо виртуальной клавиатуры. Это происходит мгновенно и работает на всех раскладках клавиатуры (AZERTY, QWERTY и т.д.).

Автоматический отчет о тестировании

Каждое действие (tap, type, swipe, assert...) автоматически записывается со скриншотом. В конце теста в /tmp/phantom-report-xxx/ генерируется отчет в формате markdown.

Безопасность

• Все системные команды проходят через execFile (без оболочки)

• Входные данные проверяются регулярными выражениями: bundle IDs, UDIDs, package names, AVD names, URLs

• Предикаты iOS экранированы (защита от инъекций)

• Текст Android экранирован для оболочки устройства

• Ноль as any, ноль exec() shell

Конфигурация

Опциональные переменные окружения:

• PHANTOM_WDA_PATH — путь к WebDriverAgent (по умолчанию: ~/.appium/...)

• PHANTOM_WDA_URL — URL WDA (по умолчанию: http://localhost:8100)

Вклад в проект

См. CONTRIBUTING.md для локальной настройки, шаблона добавления нового инструмента, соглашений об именовании и рабочего процесса PR.

См. также:

• docs/LIMITATIONS.md — известные ограничения + обходные пути

• docs/PATTERNS.md — практические рецепты (DatePicker iOS, нижние листы и т.д.)

• docs/FEATURE_REQUESTS.md — функции, приоритетные для следующих версий

• docs/CHANGES_2026-04-30.md — примечания к выпуску v2.3.0

Устранение неполадок

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