Skip to main content
Glama
deenesfrjakoruzh
nthImpulse

phantom-mcp

by nthImpulse
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

前置要求

工具

用途

检查方法

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

通过 bundle ID / 包名启动应用

kill_app

关闭应用

分析与自动化 (Tier 3)

工具

描述

accessibility_audit

辅助功能审计：缺失标签、点击目标过小、图片缺少 alt 文本

test_report

自动测试报告：start 开始跟踪，end 生成 markdown。每个操作都会自动记录。

visual_diff

逐像素比较两张截图以检测视觉回归

multi_device

在一条命令中对多个设备执行相同操作

自动运行机制

设备选择

Phantom 不会自动启动设备。它会要求你选择：

  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/ 中生成一份 markdown 报告。

安全性

  • 所有系统命令均通过 execFile 执行 (无 shell)

  • 输入通过正则表达式验证：bundle ID、UDID、包名、AVD 名称、URL

  • iOS 谓词已转义 (防止注入)

  • Android 文本已为设备 shell 转义

  • 零 as any，零 exec() shell

配置

可选环境变量：

  • PHANTOM_WDA_PATH — WebDriverAgent 的路径 (默认: ~/.appium/...)

  • PHANTOM_WDA_URL — WDA URL (默认: http://localhost:8100)

贡献

请参阅 CONTRIBUTING.md 了解本地设置、添加新工具的模式、命名约定和 PR 工作流程。

另请参阅：

故障排除

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