# Appium Mcp > Appium MCP on Steroids! - **Type:** MCP server - **Install:** `agentstack add mcp-appium-appium-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [appium](https://agentstack.voostack.com/s/appium) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [appium](https://github.com/appium) - **Source:** https://github.com/appium/appium-mcp ## Install ```sh agentstack add mcp-appium-appium-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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:: ```json { "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: ```json { "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: ```bash 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: ```bash 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 [NO_UI Mode](#no_ui-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: ```bash 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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-appium-appium-mcp - Seller: https://agentstack.voostack.com/s/appium - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.