Skip to main content
Glama

Build NPM Version License Issues Last Commit

mcp-appium-visual is an AI-powered mobile automation platform with Model Context Protocol (MCP) integration. It enables seamless control of Android and iOS devices through Appium, featuring intelligent visual element detection and recovery.

Features

  • Integration with Appium for device control

  • Visual element detection and recovery (AI-based)

  • MCP support for advanced agent-driven testing workflows

  • Supports Android and iOS platforms

  • Designed for use with AI agents for intelligent automation

Related MCP server: MCP Android Agent

Prerequisites

  1. Node.js (v14 or higher)

  2. Java Development Kit (JDK)

  3. Android SDK (for Android testing)

  4. Xcode (for iOS testing, macOS only)

  5. Appium Server

  6. Android device or emulator / iOS device or simulator

Environment Setup

Before executing any commands, ensure your environment variables are properly set up:

  1. Make sure your .bash_profile, .zshrc or other shell configuration file contains the necessary environment variables:

# Example environment variables in ~/.bash_profile
export JAVA_HOME=/path/to/your/java
export ANDROID_HOME=/path/to/your/android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools
  1. Source your environment file before running MCP-Appium:

source ~/.bash_profile  # For bash
# OR
source ~/.zshrc         # For zsh

Note: The system will attempt to source your .bash_profile automatically when initializing the driver, but it's recommended to ensure proper environment setup manually before running tests in a new terminal session.

Xcode Command Line Tools Configuration

For iOS testing, proper Xcode command line tools configuration is essential:

  1. Install Xcode command line tools if not already installed:

xcode-select --install
  1. Verify the installation and check the current Xcode path:

xcode-select -p
  1. If needed, set the correct Xcode path (especially if you have multiple Xcode versions):

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
  1. Accept Xcode license agreements:

sudo xcodebuild -license accept
  1. For iOS real device testing, ensure your Apple Developer account is properly configured in Xcode:

    • Open Xcode

    • Go to Preferences > Accounts

    • Add your Apple ID if not already added

    • Download the necessary provisioning profiles

  2. Set up environment variables for iOS development:

# Add these to your ~/.bash_profile or ~/.zshrc
export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
export PATH="$DEVELOPER_DIR/usr/bin:$PATH"
  1. Source your updated configuration:

source ~/.bash_profile  # For bash
# OR
source ~/.zshrc         # For zsh

Setup

  1. Install dependencies:

npm install
  1. Install and start Appium server:

npm install -g appium
appium
  1. Set up Android device/emulator:

    • Enable Developer Options on your Android device

    • Enable USB Debugging

    • Connect device via USB or start an emulator

    • Verify device is connected using adb devices

  2. For iOS testing (macOS only):

    • Ensure Xcode command line tools are installed: xcode-select --install

    • Set up iOS simulator or connect a real device

    • Trust the development computer on the iOS device if using a real device

Running Tests

  1. Build the project:

npm run build
  1. Start the MCP server:

npm run dev
  1. In a new terminal, run the test:

npm test

Test Configuration

Android Configuration

The example test uses the Android Settings app as a demo. To test your own app:

  1. Edit examples/appium-test.ts:

    • Update deviceName to match your device

    • Set app path to your APK file, or

    • Update appPackage and appActivity for an installed app

  2. Common capabilities configuration:

const capabilities: AppiumCapabilities = {
  platformName: "Android",
  deviceName: "YOUR_DEVICE_NAME",
  automationName: "UiAutomator2",
  // For installing and testing an APK:
  app: "./path/to/your/app.apk",
  // OR for testing an installed app:
  appPackage: "your.app.package",
  appActivity: ".MainActivity",
  noReset: true,
};

iOS Configuration

For iOS testing using the new Xcode command line support:

  1. Example configuration in examples/xcode-appium-example.ts:

const capabilities: AppiumCapabilities = {
  platformName: "iOS",
  deviceName: "iPhone 13", // Your simulator or device name
  automationName: "XCUITest",
  udid: "DEVICE_UDID", // Get this from XcodeCommands.getIosSimulators()
  // For installing and testing an app:
  app: "./path/to/your/app.app",
  // OR for testing an installed app:
  bundleId: "com.your.app",
  noReset: true,
};

Available Actions

The MCP server supports various Appium actions:

  1. Element Interactions:

    • Find elements

    • Tap/click elements with W3C Actions API (See "W3C Standard Gestures" section)

    • Type text

    • Scroll to element with W3C Actions API

    • Long press

  2. App Management:

    • Launch/close app

    • Reset app

    • Get current package/activity

  3. Device Controls:

    • Screen orientation

    • Keyboard handling

    • Device lock/unlock

    • Screenshots

    • Battery info

  4. Advanced Features:

    • Context switching (Native/WebView)

    • File operations

    • Notifications

    • Custom gestures

  5. Xcode Command Line Tools (iOS only):

    • Manage iOS simulators (boot, shutdown)

    • Install/uninstall apps on simulators

    • Launch/terminate apps

    • Take screenshots

    • Record videos

    • Create/delete simulators

    • Get device types and runtimes

W3C Standard Gestures

The MCP-Appium library now implements the W3C WebDriver Actions API for touch gestures, which is the modern standard for mobile automation.

W3C Actions for Tap Elements

The tapElement method now uses the W3C Actions API with intelligent fallbacks:

// The method will try in this order:
// 1. Standard WebdriverIO click()
// 2. W3C Actions API
// 3. Legacy TouchAction API (fallback for backward compatibility)
await appium.tapElement("//android.widget.Button[@text='OK']");
// or using the click alias
await appium.click("//android.widget.Button[@text='OK']");

W3C Actions for Scrolling

The scrollToElement method now uses W3C Actions API:

// Uses W3C Actions API for more reliable scrolling
await appium.scrollToElement(
  "//android.widget.TextView[@text='About phone']", // selector
  "down", // direction: "up", "down", "left", "right"
  "xpath", // strategy
  10 // maxScrolls
);

Custom W3C Gestures

You can create your own custom W3C gestures using the executeMobileCommand method:

// Create custom W3C Actions API gesture
const w3cActions = {
  actions: [
    {
      type: "pointer",
      id: "finger1",
      parameters: { pointerType: "touch" },
      actions: [
        // Move to start position
        { type: "pointerMove", duration: 0, x: startX, y: startY },
        // Press down
        { type: "pointerDown", button: 0 },
        // Move to end position over duration milliseconds
        {
          type: "pointerMove",
          duration: duration,
          origin: "viewport",
          x: endX,
          y: endY,
        },
        // Release
        { type: "pointerUp", button: 0 },
      ],
    },
  ],
};

// Execute the W3C Actions using executeScript
await appium.executeMobileCommand("performActions", [w3cActions.actions]);

See examples/w3c-actions-swipe-demo.ts for more examples of W3C standard gesture implementations.

Using Xcode Command Line Tools

The new XcodeCommands class provides powerful tools for iOS testing:

import { XcodeCommands } from "../src/lib/xcode/xcodeCommands.js";

// Check if Xcode CLI tools are installed
const isInstalled = await XcodeCommands.isXcodeCliInstalled();

// Get available simulators
const simulators = await XcodeCommands.getIosSimulators();

// Boot a simulator
await XcodeCommands.bootSimulator("SIMULATOR_UDID");

// Install an app
await XcodeCommands.installApp("SIMULATOR_UDID", "/path/to/app.app");

// Launch an app
await XcodeCommands.launchApp("SIMULATOR_UDID", "com.example.app");

// Take a screenshot
await XcodeCommands.takeScreenshot("SIMULATOR_UDID", "/path/to/output.png");

// Shutdown a simulator
await XcodeCommands.shutdownSimulator("SIMULATOR_UDID");

Using the Click Function

The click() method provides a more intuitive alternative to tapElement():

// Using the click method
await appium.click("//android.widget.Button[@text='OK']");

// This is equivalent to:
await appium.tapElement("//android.widget.Button[@text='OK']");

Troubleshooting

  1. Device not found:

    • Check adb devices output

    • Verify USB debugging is enabled

    • Try reconnecting the device

  2. App not installing:

    • Verify APK path is correct

    • Check device has enough storage

    • Ensure app is signed for debug

  3. Elements not found:

    • Use Appium Inspector to verify selectors

    • Check if elements are visible on screen

    • Try different locator strategies

  4. Connection issues:

    • Verify Appium server is running

    • Check port conflicts

    • Ensure correct capabilities are set

  5. iOS Simulator issues:

    • Verify Xcode command line tools are installed: xcode-select -p

    • Check simulator UDID is correct using xcrun simctl list devices

    • Close and restart simulator if it becomes unresponsive

Contributing

Feel free to submit issues and pull requests for additional features or bug fixes.

License

MIT

Available Tools

110 tools
appium-screenshotC

Take a screenshot using Appium

Inputs: name (required).

capture-ui-locatorsC

Capture all UI elements and their locators for future use

Inputs: elementType, saveToFile, refreshSource.

clear-elementC

Clear text from an input element

Inputs: selector (required), strategy.

close-appB

Close the app associated with the current Appium session

Inputs: no named parameters.

close-appiumB

Close the current Appium driver session

Inputs: no named parameters.

element-existsC

Check if an element exists on the current page

Inputs: selector (required), strategy.

execute-adb-commandC

Execute a custom ADB command

Inputs: command (required).

execute-mobile-commandC

Execute a custom mobile command for iOS or Android

Inputs: command (required), args.

extract-locatorsC

Extract element locators from UI XML source

Inputs: xmlSource (required), elementType, maxResults.

find-by-ios-class-chainC

Find an element using iOS class chain (iOS only)

Inputs: classChain (required), timeoutMs.

find-by-ios-predicateB

Find an element using iOS predicate string (iOS only)

Inputs: predicateString (required), timeoutMs.

find-by-textC

Generate XPath to find element by text

Inputs: text (required), platformName (required), exactMatch, elementType.

find-elements-by-textC

Find all elements containing specific text

Inputs: text (required).

generate-element-locatorsC

Generate multiple types of locators for an element

Inputs: selector (required), strategy.

generate-test-scriptC

Generate Appium test script from actions

Inputs: platformName (required), actions (required), appPackage, bundleId.

get-battery-infoB

Get the device battery information

Inputs: no named parameters.

get-contextsB

Get all available contexts (NATIVE_APP, WEBVIEW, etc.)

Inputs: no named parameters.

get-current-activityB

Get the current Android activity name

Inputs: no named parameters.

get-current-contextC

Get the current context

Inputs: no named parameters.

get-current-packageB

Get the current active app package name

Inputs: no named parameters.

get-device-timeB

Get the current device time

Inputs: no named parameters.

get-element-attributesC

Get all available attributes of an element

Inputs: selector (required), strategy.

get-element-textC

Get text content from a UI element

Inputs: selector (required), strategy.

get-element-treeC

Get a hierarchical view of the UI elements (similar to Appium Inspector)

Inputs: maxDepth.

get-orientationB

Get the current device orientation

Inputs: no named parameters.

get-page-sourceB

Get the XML representation of the current UI

Inputs: no named parameters.

has-text-in-screenA

Check if specific text exists anywhere on the current screen

Inputs: text (required).

hide-keyboardB

Hide the keyboard if it's currently visible

Inputs: no named parameters.

initialize-appiumC

Initialize an Appium driver session for mobile automation

Inputs: platformName (required), deviceName (required), udid, app, +8 more.

inspect-and-actC

Inspect UI to identify element locators and then perform an action

Inputs: action (required), elementIdentifier, text, longPressMs, +4 more.

inspect-and-tapC

Inspect an element using one locator, then tap using the best available locator

Inputs: selector (required), strategy, preferredOrder.

inspect-elementC

Get detailed information about an element (for debugging)

Inputs: selector (required), strategy.

install-appC

Install an Android application APK

Inputs: deviceId (required), apkPath (required).

is-device-lockedA

Check if the device is currently locked

Inputs: no named parameters.

launch-appC

Launch an app on an Android device

Inputs: deviceId (required), packageName (required), activityName.

launch-appium-appB

Launch the app associated with the current Appium session

Inputs: no named parameters.

list-devicesB

List all connected Android devices

Inputs: no named parameters.

list-installed-packagesB

List all installed packages on an Android device

Inputs: deviceId (required).

list-ios-simulatorsB

Get list of available iOS simulators

Inputs: no named parameters.

lock-deviceC

Lock the device screen

Inputs: durationSec.

long-pressC

Perform a long press gesture on an element

Inputs: selector (required), duration, strategy.

open-notificationsB

Open the notifications panel (Android only)

Inputs: no named parameters.

perform-element-actionC

Perform a specific action on an element using various locator strategies

Inputs: action (required), locatorType (required), locatorValue (required), actionParams, +1 more.

perform-touch-idC

Simulate Touch ID fingerprint (iOS only)

Inputs: match (required).

perform-w3c-gestureB

Perform touch gestures using the W3C Actions API (more reliable than TouchAction API)

Inputs: actionType (required), startX (required), startY (required), endX, +6 more.

press-key-codeC

Press an Android key code

Inputs: keycode (required).

pull-fileC

Pull a file from the device

Inputs: path (required).

push-fileC

Push a file to the device

Inputs: path (required), data (required).

reset-appB

Reset the app (terminate and relaunch) associated with the current Appium session

Inputs: no named parameters.

save-ui-hierarchyC

Save UI hierarchy XML to a file

Inputs: xmlSource (required), filePath (required).

scroll-screenC

Scroll the screen in a specified direction

Inputs: direction (required), distance.

scroll-to-elementC

Scroll until an element becomes visible

Inputs: selector (required), direction, strategy, maxScrolls.

send-key-eventC

Send a key event to the device (e.g., HOME, BACK)

Inputs: keyEvent (required).

send-keysC

Send text input to a UI element

Inputs: selector (required), text (required), strategy.

send-keys-by-ios-class-chainC

Send text to an element using iOS class chain (iOS only)

Inputs: classChain (required), text (required), timeoutMs.

send-keys-by-ios-predicateB

Send text to an element using iOS predicate string (iOS only)

Inputs: predicateString (required), text (required), timeoutMs.

send-keys-to-deviceC

Send keys directly to the device without focusing on any element

Inputs: text (required).

set-orientationC

Set the device orientation

Inputs: orientation (required).

shake-deviceB

Simulate shake gesture (iOS only)

Inputs: no named parameters.

smart-tapB

Intelligently tap an element trying different locator strategies in a specific order

Inputs: elementIdentifier (required), text, timeoutMs.

start-recordingC

Start recording the screen

Inputs: videoType, timeLimit, videoQuality, videoFps.

stop-recordingC

Stop recording the screen and get the recording data

Inputs: outputPath (required).

swipeC

Perform a swipe gesture on the screen

Inputs: startX (required), startY (required), endX (required), endY (required), +1 more.

switch-contextC

Switch between contexts (e.g., NATIVE_APP, WEBVIEW)

Inputs: context (required).

take-screenshotC

Take a screenshot on an Android device

Inputs: deviceId (required), outputPath (required).

tap-by-ios-class-chainC

Tap on an element using iOS class chain (iOS only)

Inputs: classChain (required), timeoutMs.

tap-by-ios-predicateB

Tap on an element using iOS predicate string (iOS only)

Inputs: predicateString (required), timeoutMs.

tap-elementB

Tap on a UI element identified by a selector

Inputs: selector (required), strategy.

tap-element-by-textC

Tap on an element containing specific text

Inputs: text (required).

uninstall-appC

Uninstall an Android application

Inputs: deviceId (required), packageName (required).

unlock-deviceB

Unlock the device screen

Inputs: no named parameters.

wait-for-elementC

Wait for an element to be visible on screen

Inputs: selector (required), strategy, timeoutMs.

xcode_add_media_to_simulatorC

Add photos/videos to a simulator

Inputs: udid (required), mediaPaths (required).

xcode_boot_simulatorC

Boot an iOS simulator

Inputs: udid (required).

xcode_check_cli_installedB

Check if Xcode command line tools are installed

Inputs: no named parameters.

xcode_clear_simulator_locationC

Clear the location of a simulator

Inputs: udid (required).

xcode_configure_simulator_preferencesB

Configure simulator preferences in batch

Inputs: udid (required), preferences (required).

xcode_copy_to_simulatorC

Copy files to a simulator (limited to media files)

Inputs: udid (required), sourcePath (required), destinationPath (required).

xcode_create_simulatorC

Create a new iOS simulator

Inputs: name (required), deviceTypeId (required), runtimeId (required).

xcode_delete_simulatorC

Delete an iOS simulator

Inputs: udid (required).

xcode_erase_simulatorC

Erase all data from a simulator

Inputs: udid (required).

xcode_get_device_typesB

Get available device types for simulators

Inputs: no named parameters.

xcode_get_ios_simulatorsB

Get a list of available iOS simulators

Inputs: no named parameters.

xcode_get_pathB

Get the path to the Xcode installation

Inputs: no named parameters.

xcode_get_privacy_permissionC

Get privacy permission status for an app

Inputs: udid (required), bundleId (required), service (required).

xcode_get_runtimesB

Get available runtimes for simulators

Inputs: no named parameters.

xcode_get_simulator_infoC

Get detailed information about a specific simulator

Inputs: udid (required).

xcode_get_simulator_logsC

Get logs from a simulator

Inputs: udid (required), predicate.

xcode_get_simulator_statusB

Get the status of all simulators

Inputs: no named parameters.

xcode_get_system_infoC

Get system information from a simulator

Inputs: udid (required).

xcode_grant_privacy_permissionC

Grant privacy permission to an app

Inputs: udid (required), bundleId (required), service (required).

xcode_install_appC

Install an app on a simulator

Inputs: udid (required), appPath (required).

xcode_install_cliA

Install Xcode command line tools (requires user interaction)

Inputs: no named parameters.

xcode_launch_appC

Launch an app on a simulator

Inputs: udid (required), bundleId (required), args, waitForDebugger.

xcode_list_installed_appsC

List all installed apps on a simulator

Inputs: udid (required).

xcode_open_urlB

Open a URL on a simulator

Inputs: udid (required), url (required).

xcode_push_notificationC

Push a notification to a simulator

Inputs: udid (required), bundleId (required), payload (required).

xcode_record_videoC

Start recording video of a simulator (returns process info)

Inputs: udid (required), outputPath (required).

xcode_reset_privacy_permissionC

Reset privacy permission for an app

Inputs: udid (required), bundleId (required), service (required).

xcode_revoke_privacy_permissionC

Revoke privacy permission from an app

Inputs: udid (required), bundleId (required), service (required).

xcode_set_hardware_keyboardC

Enable/disable hardware keyboard for a simulator

Inputs: udid (required), enabled (required).

xcode_set_simulator_locationC

Set the location of a simulator

Inputs: udid (required), latitude (required), longitude (required).

xcode_set_simulator_preferenceC

Set a specific simulator preference

Inputs: udid (required), domain (required), key (required), value (required).

xcode_shake_deviceC

Simulate shake gesture on a simulator

Inputs: udid (required).

xcode_shutdown_simulatorB

Shutdown an iOS simulator

Inputs: udid (required).

xcode_take_screenshotC

Take a screenshot of a simulator

Inputs: udid (required), outputPath (required).

xcode_terminate_appC

Terminate an app on a simulator

Inputs: udid (required), bundleId (required).

xcode_trigger_memory_warningC

Trigger memory warning on a simulator

Inputs: udid (required).

xcode_uninstall_appC

Uninstall an app from a simulator

Inputs: udid (required), bundleId (required).

xcode_wait_for_simulatorC

Wait for a simulator to be ready

Inputs: udid (required), timeoutMs.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 110 tools

    Disambiguation2/5

    There is significant overlap and ambiguity between tools, making it difficult for an agent to choose correctly. For example, 'take-screenshot' and 'appium-screenshot' appear redundant, 'close-app' and 'close-appium' are confusingly similar, and many tap/send-keys variants (e.g., 'tap-element', 'smart-tap', 'tap-by-ios-class-chain') have unclear boundaries. The descriptions help somewhat, but the sheer number of overlapping tools increases misselection risk.

    Naming Consistency3/5

    Naming is mixed with inconsistent patterns. Most tools use kebab-case (e.g., 'get-element-text'), but some use snake_case (e.g., 'xcode_add_media_to_simulator'), and verbs vary widely (e.g., 'get-', 'list-', 'perform-', 'execute-'). The xcode_* tools follow a consistent prefix pattern, but overall the conventions are not uniform across the set, reducing predictability.

    Tool Count2/5

    With 110 tools, the count is excessive for an MCP server, likely overwhelming agents and causing decision paralysis. While Appium automation is broad, many tools could be consolidated (e.g., multiple screenshot or tap methods). A well-scoped server should have fewer, more generalized tools, making this set feel bloated and inefficient.

    Completeness5/5

    The tool set provides comprehensive coverage for mobile automation with Appium, including device management, UI interaction, testing, and simulator control. It supports CRUD-like operations for apps, elements, and files, and covers both Android and iOS platforms. No obvious gaps are present; agents can perform end-to-end automation tasks without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      A Model Context Protocol server that enables scalable mobile automation through a platform-agnostic interface for iOS and Android devices, allowing agents and LLMs to interact with mobile applications using accessibility snapshots or coordinate-based interactions.
      35
      45,799 npm
      10,554
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI agents to control and automate Android devices through natural language, supporting actions like app management, UI interactions, and device monitoring.
      60
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables scalable mobile automation for iOS and Android through a platform-agnostic interface, allowing LLMs to interact with mobile applications via accessibility snapshots or screenshot-based inputs.
      19
      2
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that provides Android Debug Bridge functionality for automating Android devices, enabling remote device management, screen operations, app management, file operations, and shell command execution.
      20
      9 npm
      1
      MIT