What is the MCP Appium Server?

The MCP Appium Server is an implementation of the Model Context Protocol (MCP) for mobile app automation using Appium. It acts as a bridge, allowing AI models to access and interact with external data sources and tools for testing mobile applications.

What are the prerequisites for using the MCP Appium Server?

The prerequisites include Node.js (v14 or higher), Java Development Kit (JDK), Android SDK (for Android testing), Xcode (for iOS testing), and Appium Server.

How do I set up the environment variables?

Ensure your .bash_profile or .zshrc file contains necessary environment variables like JAVA_HOME and ANDROID_HOME. Source the file using source ~/.bash_profile or source ~/.zshrc.

How do I install the MCP Appium Server dependencies?

Navigate to the project directory in your terminal and run npm install.

How do I start the Appium server?

Install Appium globally using npm install -g appium and then start it by running appium in the terminal.

How do I configure Android devices or emulators for testing?

Enable Developer Options and USB Debugging on your Android device. Connect the device via USB or start an emulator and verify the connection using adb devices.

How do I configure iOS devices or simulators for testing?

Ensure Xcode command line tools are installed using xcode-select --install. Set up iOS simulators or connect a real device. Trust the development computer on the iOS device if using a real device.

How do I run tests with the MCP Appium Server?

Build the project using npm run build, start the MCP server using npm run dev, and then run the tests in a new terminal using npm test.

How do I configure the test for Android?

Edit the examples/appium-test.ts file. Update deviceName to match your device. Set the app path to your APK file or update appPackage and appActivity for an installed app.

How do I configure the test for iOS?

Use the example configuration in examples/xcode-appium-example.ts. Set platformName to “iOS”, update deviceName, and set the udid from XcodeCommands.getIosSimulators(). Specify the app path or bundleId for the app you want to test.

What actions does the MCP server support?

The MCP server supports element interactions, app management, device controls, advanced features like context switching and file operations, and Xcode Command Line Tools (iOS only).

How do I perform a tap action on an element?

Use the appium.tapElement(selector) method or its alias appium.click(selector). The method intelligently falls back to W3C Actions API or Legacy TouchAction API if needed.

How do I scroll to an element?

Use the appium.scrollToElement(selector, direction, strategy, maxScrolls) method, which uses the W3C Actions API for reliable scrolling.

Can I create custom gestures with the MCP Appium Server?

Yes, you can create custom W3C gestures using the executeMobileCommand method. Refer to examples/w3c-actions-swipe-demo.ts for examples.

How do I use Xcode Command Line Tools with the MCP Appium Server?

Import the XcodeCommands class and use its methods to manage iOS simulators, install apps, launch apps, take screenshots, and shutdown simulators.

What should I do if the device is not found?

Check the adb devices output, verify USB debugging is enabled, and try reconnecting the device.

What should I do if the app is not installing?

Verify the APK path is correct, check if the device has enough storage, and ensure the app is signed for debug.

What should I do if elements are not found?

Use Appium Inspector to verify selectors, check if elements are visible on the screen, and try different locator strategies.

What should I do if there are connection issues?

Verify the Appium server is running, check for port conflicts, and ensure correct capabilities are set.

What should I do if there are iOS Simulator issues?

Verify Xcode command line tools are installed using xcode-select -p, check the simulator UDID is correct using xcrun simctl list devices, and close and restart the simulator if it becomes unresponsive.

How does UBOS enhance the MCP Appium Server experience?

UBOS enhances the MCP Appium Server by providing AI-powered test script generation, intelligent test execution and reporting, seamless integration with other UBOS assets, Multi-Agent Systems capabilities, and custom AI Agent integration.