phantom-mcp

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

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

Установка

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

22 инструмента

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

Наблюдение

Утверждения (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 (без оболочки shell)

• Входные данные проверяются регулярными выражениями: bundle ID, UDID, package name, имена AVD, URL

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

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

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

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

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

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

• PHANTOM_WDA_URL — URL WDA (по умолчанию: 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