MCP Appium - MCP server for Mobile Development and Automation | iOS, Android, Simulator, Emulator, and Real Devices

MCP Appium is an intelligent MCP (Model Context Protocol) server designed to empower AI assistants with a robust suite of tools for mobile automation. It streamlines mobile app testing by enabling natural language interactions, intelligent locator generation, and automated test creation for both Android and iOS platforms.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Remote server security and trust model
• Available Tools
• Plugin API
• Client Support
• Usage Examples
• Contributing
• License

🚀 Features

• Cross-Platform Support: Automate tests for both Android (UiAutomator2) and iOS (XCUITest).
• AI-Powered Element Finding: Locate UI elements using natural language descriptions powered by vision models - no need for complex XPath or selectors.
• Intelligent Locator Generation: AI-powered element identification using priority-based strategies.
• Interactive Session Management: Easily create and manage sessions on local mobile devices.
• Smart Element Interactions: Perform actions like clicks, text input, screenshots, and element finding.
• Automated Test Generation: Generate Java/TestNG test code from natural language descriptions.
• Page Object Model Support: Utilize built-in templates that follow industry best practices.
• Flexible Configuration: Customize capabilities and settings for different environments.
• Multilingual Support: Use your native language - AI handles all interactions naturally in any language (English, Spanish, Chinese, Japanese, Korean, etc.).

📋 Prerequisites

Before you begin, ensure you have the following installed:

System Requirements

• Node.js (v22 or higher)
• npm or yarn
• Java Development Kit (JDK) (8 or higher)
• Android SDK (for Android testing)
• Xcode (for iOS testing on macOS)

MCP Appium supports two driver modes:

• Embedded local drivers: when appium_session_management creates an android or ios session without remoteServerUrl, MCP Appium uses the bundled appium-uiautomator2-driver or appium-xcuitest-driver dependency directly. You still need the platform toolchains below, but you do not need to install a global Appium server or run appium driver install uiautomator2 / appium driver install xcuitest for this mode.
• Remote WebDriver/Appium server: when remoteServerUrl is provided to action=create or action=attach, MCP Appium uses the webdriver client to talk to that existing server. In this mode the remote server is responsible for its installed drivers, plugins, device access, and capability handling. Use this mode for platform=general; embedded local creation is available only for Android and iOS.

Mobile Testing Setup for embedded local drivers

#### Android

1. Install Android Studio and the Android SDK.
2. Set the ANDROID_HOME environment variable.
3. Add the Android SDK tools to your system's PATH.
4. Enable USB debugging on your Android device.
5. Install the Android platform tools/build tools and keep adb available on PATH.

#### iOS (macOS only)

1. Install Xcode from the App Store.
2. Install the Xcode Command Line Tools: xcode-select --install.
3. Install iOS simulators through Xcode.
4. For real device testing, enable Developer Mode on the device and sign in to your Apple ID in Xcode (Settings → Accounts). Use appium_prepare_ios_real_device to download and sign WebDriverAgent in a single call - it will guide you through provisioning profile selection and return capabilities for session startup.

🛠️ Installation

Standard config works in most of the tools::

{
  "mcpServers": {
    "appium-mcp": {
      "disabled": false,
      "timeout": 100,
      "type": "stdio",
      "command": "npx",
      "args": ["appium-mcp@latest"],
      "env": {
        "ANDROID_HOME": "/path/to/android/sdk",
        "CAPABILITIES_CONFIG": "/path/to/your/capabilities.json"
      }
    }
  }
}

In Cursor IDE

The easiest way to install MCP Appium in Cursor IDE is using the one-click install button:

This will automatically configure the MCP server in your Cursor IDE settings. Make sure to update the ANDROID_HOME environment variable in the configuration to match your Android SDK path.

#### Or install manually:

Go to Cursor Settings → MCP → Add new MCP Server. Name it to your liking, use command type with the command npx -y appium-mcp@latest. You can also verify config or add command arguments via clicking Edit.

Here is the recommended configuration:

{
  "appium-mcp": {
    "disabled": false,
    "timeout": 100,
    "type": "stdio",
    "command": "npx",
    "args": ["appium-mcp@latest"],
    "env": {
      "ANDROID_HOME": "/Users/xyz/Library/Android/sdk"
    }
  }
}

Note: Make sure to update the ANDROID_HOME path to match your Android SDK installation path.

With Gemini CLI

Use the Gemini CLI to add the MCP Appium server:

gemini mcp add appium-mcp npx -y appium-mcp@latest

This will automatically configure the MCP server for use with Gemini. Make sure to update the ANDROID_HOME environment variable in the configuration to match your Android SDK path.

With Claude Code CLI

Use the Claude Code CLI to add the MCP Appium server:

claude mcp add appium-mcp -- npx -y appium-mcp@latest

This will automatically configure the MCP server for use with Claude Code. Make sure to update the ANDROID_HOME environment variable in the configuration to match your Android SDK path.

⚙️ Configuration

Environment Variables

Note: For embedded local Android/iOS sessions, MCP Appium already includes the UiAutomator2 and XCUITest driver packages. The system-level requirements are the platform toolchains (ANDROID_HOME, Java, Android SDK tools, Xcode/iOS signing or simulator setup). For remote sessions, configure those requirements on the remote Appium/WebDriver server instead.