Skip to main content
Glama
deenesjakoruzh

MCP Appium Server

by Rahulec08
npmGitHub
TypeScript
Apache 2.0
7
33
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP Appium Server

A Model Context Protocol (MCP) server implementation for mobile app automation using Appium.

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

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

A Model Context Protocol (MCP) server that enables mobile app automation using Appium, supporting various device interactions, element operations, and app management through a standardized protocol.

  1. Prerequisites
    1. Environment Setup
      1. Xcode Command Line Tools Configuration
    2. Setup
      1. Running Tests
        1. Test Configuration
          1. Android Configuration
          2. iOS Configuration
        2. Available Actions
          1. W3C Standard Gestures
            1. W3C Actions for Tap Elements
            2. W3C Actions for Scrolling
            3. Custom W3C Gestures
          2. Using Xcode Command Line Tools
            1. Using the Click Function
              1. Troubleshooting
                1. Contributing
                  1. License

                    Related Resources

                    Related MCP Servers

                    • ABAP-ADT-API MCP-Server

                      mario-andreschak
                      A
                      security
                      A
                      license
                      A
                      quality
                      A Model Context Protocol server that facilitates communication between ABAP systems and MCP clients, providing tools for managing ABAP objects, handling transport requests, and performing code analysis to enhance ABAP development workflows.
                      Last updated -
                      56
                      MIT License
                      • Linux
                      • Apple

                    • DroidMind

                      hyperb1iss
                      A
                      security
                      A
                      license
                      A
                      quality
                      A Model Context Protocol (MCP) server that enables AI assistants to control and interact with Android devices, allowing for device management, app debugging, system analysis, and UI automation through natural language commands.
                      Last updated -
                      8
                      240
                      Apache 2.0
                      • Linux
                      • Apple

                    • Mobile Next MCP Serverofficial

                      mobile-next
                      A
                      security
                      A
                      license
                      A
                      quality
                      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.
                      Last updated -
                      17
                      2,810
                      2,096
                      Apache 2.0
                      • Apple
                      • Linux

                    • Mobile Next MCP

                      EmpathySlainLovers
                      A
                      security
                      A
                      license
                      A
                      quality
                      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.
                      Last updated -
                      17
                      2,810
                      2
                      Apache 2.0
                      • Apple
                      • Linux

                    View all related MCP servers

                    Appeared in Searches

                    New MCP Servers

                    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/Rahulec08/appium-mcp'

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