Appium Mcp

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

[](https://opensource.org/licenses/Apache-2.0)

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](#-features)
• [Prerequisites](#-prerequisites)
• [Installation](#️-installation)
• [Configuration](#️-configuration)
• [Available Tools](#-available-tools)
• [Plugin API](#-plugin-api)
• [Client Support](#-client-support)
• [Usage Examples](#-usage-examples)
• [Contributing](#-contributing)
• [License](#-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:

[](https://cursor.com/en-US/install-mcp?name=appium-mcp&config=eyJkaXNhYmxlZCI6ZmFsc2UsInRpbWVvdXQiOjEwMCwidHlwZSI6InN0ZGlvIiwiZW52Ijp7IkFORFJPSURfSE9NRSI6Ii9Vc2Vycy94eXovTGlicmFyeS9BbmRyb2lkL3NkayJ9LCJjb21tYW5kIjoibnB4IGFwcGl1bS1tY3BAbGF0ZXN0In0%3D)

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.

| Variable | Required | Description | | ----------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CAPABILITIES_CONFIG | Optional | Absolute path to a capabilities.json file with per-platform capability presets | | SCREENSHOTS_DIR | Optional | Directory where screenshots and screen recordings are saved. Defaults to the current working directory | | NO_UI | Optional | Set to true or 1 to disable HTML UI components — faster responses, fewer tokens. See [NOUI Mode](#noui-mode) | | APPIUM_MCP_ON_CLIENT_DISCONNECT | Optional | Session cleanup when the MCP client disconnects: delete_all (default) deletes MCP-owned Appium sessions (safeDeleteAllSessions); skip keeps those sessions across disconnects (e.g. HTTP/stream clients that reconnect). Attached/remote sessions are not removed by this path. See [MCP disconnect behavior](#mcp-disconnect-behavior). | | APPIUM_MCP_WDA_APP_PATH | Optional | Absolute path to a pre-extracted WebDriverAgentRunner-Runner.app bundle. When set, prepare_ios_simulator skips all GitHub downloads and uses this bundle directly — useful in environments where external downloads are blocked | | REMOTE_SERVER_URL_ALLOW_REGEX | Optional | Regex pattern that remote Appium server URLs must match. Defaults to ^https?:// | | AI_VISION_ENABLED | Optional | Set to true to register the appium_ai tool (vision-based element finding). When unset or false, the AI tool is not registered and the LLM has no way to invoke vision-based finding. Requires AI_VISION_API_BASE_URL and AI_VISION_API_KEY to also be set, otherwise the server fails to start. | | AI_VISION_API_BASE_URL | Required when AI_VISION_ENABLED=true | Base URL of the OpenAI-compatible vision model API | | AI_VISION_API_KEY | Required when AI_VISION_ENABLED=true | API key for the vision model provider | | AI_VISION_MODEL | Optional | Vision model name (default: Qwen3-VL-235B-A22B-Instruct) | | AI_VISION_COORD_TYPE | Optional | Coordinate type: normalized (default) or absolute | | AI_VISION_IMAGE_MAX_WIDTH | Optional | Max image width in pixels before compression (default: 1080) | | AI_VISION_IMAGE_QUALITY | Optional | JPEG quality 1–100 for compressed screenshots sent to the vision API (default: 80) | | APPIUM_MCP_DOCS_ENABLED | Optional | Set to true (or 1/yes/on) to register the documentation tools (appium_documentation_query, appium_skills). Opt-in and disabled by default. Requires the optional @appium/mcp-documentation package (embeddings cache + ML stack) to be installed separately; when unset it is never downloaded. See [Documentation Tools (opt-in)](#documentation-tools-opt-in). | | SENTENCE_TRANSFORMERS_MODEL | Optional | Hugging Face model used for semantic search in Appium documentation queries (default: Xenova/all-MiniLM-L6-v2). Only applies when APPIUM_MCP_DOCS_ENABLED is set. | | APPIUM_MCP_PERSIST_REMOTE_SESSIONS_PATH | Optional | Directory path for persisted attached remote session info. When set, attached remote sessions are stored as JSON files in that directory and can be rehydrated after restart. | | APPIUM_MCP_EVIDENCE | Optional | Set to true or 1 to attach a structured action evidence record (locator, resolved element id, context, timing, normalized error code) to appium_find_element and appium_gesture responses as an application/vnd.appium.evidence+json resource block, for CI/debugging. Disabled by default; responses are unchanged when unset. | | APPIUM_MCP_OTEL_ENABLED | Optional | Set to true to enable OpenTelemetry tracing (disabled by default). | | APPIUM_MCP_OTEL_INCLUDE_ARGUMENT_VALUES | Optional | Set to true to include sanitized non-sensitive argument values in spans; disabled by default because values may contain sensitive data. | | OTEL_SERVICE_NAME | Optional | Service name reported to the OpenTelemetry collector (example: appium-mcp). | | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Optional | OTLP/HTTP traces endpoint (example: http://127.0.0.1:4318/v1/traces). | | OTEL_TRACES_SAMPLER | Optional | Trace sampling strategy; parentbased_always_on samples new root traces and follows parent decisions. | | OTEL_RESOURCE_ATTRIBUTES | Optional | Comma-separated key=value pairs attached as resource attributes to every span (example: testcase.id=my-test-123,team=platform). |

OpenTelemetry tracing

OpenTelemetry tracing is disabled by default. Set APPIUM_MCP_OTEL_ENABLED=true to initialize the Node.js OpenTelemetry SDK before the MCP server is constructed. The SDK uses standard OTEL_* environment variables, for example:

APPIUM_MCP_OTEL_ENABLED=true
# Optional: include sanitized non-sensitive ar

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [appium](https://github.com/appium)
- **Source:** [appium/appium-mcp](https://github.com/appium/appium-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.