MCP Appium Server
The MCP Appium Server enables mobile app automation for both Android and iOS platforms with the following capabilities:
Session Management: Initialize and close Appium driver sessions with configurable platform-specific capabilities
UI Interaction: Tap, swipe, send text, and wait for elements using selectors like XPath or ID
App Management: Install, uninstall, launch, and reset apps
Device Control: Take screenshots, list connected devices, retrieve device information (battery, installed packages), and execute custom ADB commands
UI Analysis: Extract locators, save UI hierarchy XML, and generate XPath from text
Test Generation: Create Appium test scripts from a sequence of actions
Advanced Features: Perform W3C standard gestures, context switching, file operations, and notifications
iOS Simulator Tools: Boot, shutdown, and manage iOS simulators using Xcode command line tools
Provides capabilities for testing and automating Android applications, including device management, app installation, and UI interaction through the Appium framework.
Enables mobile app automation through Appium, supporting element interactions, app management, device controls, and advanced features like context switching and custom gestures.
Supports automation of iOS applications on devices and simulators, including element interactions and app management through the Appium framework.
Enables iOS testing functionality when running on macOS systems through integration with Xcode and iOS simulators.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Appium Server open the Settings app on my Android device and tap on the Wi-Fi option"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Node.js (v14 or higher)
Java Development Kit (JDK)
Android SDK (for Android testing)
Xcode (for iOS testing, macOS only)
Appium Server
Android device or emulator / iOS device or simulator
Environment Setup
Before executing any commands, ensure your environment variables are properly set up:
Make sure your
.bash_profile,.zshrcor 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-toolsSource your environment file before running MCP-Appium:
source ~/.bash_profile # For bash
# OR
source ~/.zshrc # For zshNote: The system will attempt to source your
.bash_profileautomatically 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:
Install Xcode command line tools if not already installed:
xcode-select --installVerify the installation and check the current Xcode path:
xcode-select -pIf needed, set the correct Xcode path (especially if you have multiple Xcode versions):
sudo xcode-select -s /Applications/Xcode.app/Contents/DeveloperAccept Xcode license agreements:
sudo xcodebuild -license acceptFor 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
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"Source your updated configuration:
source ~/.bash_profile # For bash
# OR
source ~/.zshrc # For zshSetup
Install dependencies:
npm installInstall and start Appium server:
npm install -g appium
appiumSet 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
For iOS testing (macOS only):
Ensure Xcode command line tools are installed:
xcode-select --installSet up iOS simulator or connect a real device
Trust the development computer on the iOS device if using a real device
Running Tests
Build the project:
npm run buildStart the MCP server:
npm run devIn a new terminal, run the test:
npm testTest Configuration
Android Configuration
The example test uses the Android Settings app as a demo. To test your own app:
Edit
examples/appium-test.ts:Update
deviceNameto match your deviceSet
apppath to your APK file, orUpdate
appPackageandappActivityfor an installed app
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:
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:
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
App Management:
Launch/close app
Reset app
Get current package/activity
Device Controls:
Screen orientation
Keyboard handling
Device lock/unlock
Screenshots
Battery info
Advanced Features:
Context switching (Native/WebView)
File operations
Notifications
Custom gestures
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
Device not found:
Check
adb devicesoutputVerify USB debugging is enabled
Try reconnecting the device
App not installing:
Verify APK path is correct
Check device has enough storage
Ensure app is signed for debug
Elements not found:
Use Appium Inspector to verify selectors
Check if elements are visible on screen
Try different locator strategies
Connection issues:
Verify Appium server is running
Check port conflicts
Ensure correct capabilities are set
iOS Simulator issues:
Verify Xcode command line tools are installed:
xcode-select -pCheck simulator UDID is correct using
xcrun simctl list devicesClose 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 toolsappium-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
Scored across 110 tools
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 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.
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.
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
Related MCP Connectors
MCP server for Appcircle mobile CI/CD platform.
Mozark's MCP server for AI-powered app testing: device access, test automation, and QA insights.
The Telnyx MCP server is an official implementation of the Model Context Protocol that enables AI clients (like Claude Desktop, Cursor, and OpenAI Agents) to interact with Telnyx's telephony, messaging, and AI assistant APIs. It provides comprehensive capabilities including making and managing phone calls, sending SMS/MMS messages, purchasing and configuring phone numbers, creating AI assistants with custom instructions, managing cloud storage buckets, scraping and embedding website content, and handling integration secrets. The server exists as both a local implementation and a remotely hosted version, allowing developers to integrate real-world communication infrastructure directly into AI applications.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Related MCP Servers
- AlicenseBqualityBmaintenanceA 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.3545,799 npm10,554Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA 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.60MIT
- AlicenseAqualityDmaintenanceA 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.192Apache 2.0
- AlicenseBqualityDmaintenanceA 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.209 npm1MIT