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.
MCP Appium Server
A Model Context Protocol (MCP) server implementation for mobile app automation using Appium.
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
,.zshrc
or other shell configuration file contains the necessary environment variables:
- Source your environment file before running MCP-Appium:
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:
- Install Xcode command line tools if not already installed:
- Verify the installation and check the current Xcode path:
- If needed, set the correct Xcode path (especially if you have multiple Xcode versions):
- Accept Xcode license agreements:
- 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
- Set up environment variables for iOS development:
- Source your updated configuration:
Setup
- Install dependencies:
- Install and start Appium server:
- 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
- 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
- Ensure Xcode command line tools are installed:
Running Tests
- Build the project:
- Start the MCP server:
- In a new terminal, run the test:
Test 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
deviceName
to match your device - Set
app
path to your APK file, or - Update
appPackage
andappActivity
for an installed app
- Update
- Common capabilities configuration:
iOS Configuration
For iOS testing using the new Xcode command line support:
- Example configuration in
examples/xcode-appium-example.ts
:
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:
W3C Actions for Scrolling
The scrollToElement
method now uses W3C Actions API:
Custom W3C Gestures
You can create your own custom W3C gestures using the executeMobileCommand
method:
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:
Using the Click Function
The click()
method provides a more intuitive alternative to tapElement()
:
Troubleshooting
- Device not found:
- Check
adb devices
output - Verify USB debugging is enabled
- Try reconnecting the device
- Check
- 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 -p
- Check simulator UDID is correct using
xcrun simctl list devices
- Close and restart simulator if it becomes unresponsive
- Verify Xcode command line tools are installed:
Contributing
Feel free to submit issues and pull requests for additional features or bug fixes.
License
MIT
You must be authenticated.
local-only server
The server can only run on the client's local machine because it depends on local resources.
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.
- Prerequisites
- Environment Setup
- Setup
- Running Tests
- Test Configuration
- Available Actions
- W3C Standard Gestures
- Using Xcode Command Line Tools
- Using the Click Function
- Troubleshooting
- Contributing
- License
Related Resources
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol (MCP) server implementation for interacting with Phabricator API. This server allows LLMs to interact with Phabricator through a standardized interface.Last updated -5Python
- AsecurityAlicenseAqualityA beginner-friendly Model Context Protocol (MCP) server that helps users understand MCP concepts, provides interactive examples, and lists available MCP servers. This server is designed to be a helpful companion for developers working with MCP. Also comes with a huge list of servers you can install.Last updated -3936JavaScriptApache 2.0
- -securityFlicense-qualityThis MCP server implementation allows users to manage and expose actions as tools from their Integration App workspace through the Model Context Protocol.Last updated -1019TypeScript
- -security-license-qualityA Model Context Protocol (MCP) server that interacts with system APIs, allowing users to check connections, search employees, register breakfast, and update chemical information by shifts.Last updated -2