← Back to directory
M

MCP Appium

Official
Appium MCP server for iOS and Android mobile automation
GitHub source repository ↗
★ 477 Stars Category · Dev Tools Very popular
57FMRS · C

MCP Appium is an Appium-organization-maintained MCP server that exposes Appium mobile automation as tools for AI assistants, covering Android and iOS across simulators, emulators, and real devices, with element finding, gestures, session management, test code generation, a plugin API, and OpenTelemetry tracing. It targets teams already using Appium for mobile testing, installs primarily over stdio via npx, and uses environment variables for capability gating. Important boundaries: it is designed as a local single-user server or a trusted CI component rather than a shared service for untrusted clients, and remote server URLs, vision model calls, and disconnect cleanup behavior all require explicit configuration.

Reliability
9/20
Security and permissions
12/20
Maintenance
11/20
Documentation
14/20
Setup experience
11/20
Read the FMRS scoring method →

MCP Appium is a Model Context Protocol server that gives AI assistants a suite of tools for mobile automation on Android (UiAutomator2) and iOS (XCUITest), covering simulators, emulators, and real devices. It supports natural-language element finding, intelligent locator generation, interactive session management, touch gestures, and automated generation of Java/TestNG test code with Page Object Model templates. It runs over stdio via npx appium-mcp@latest, bundles the UiAutomator2 and XCUITest drivers for embedded local sessions, and can also connect to a remote Appium/WebDriver server through remoteServerUrl. The project is maintained by the Appium organization under the Apache-2.0 license.

Tools

select_device
Required first step: discover available devices and select one; auto-selects when only one device is found.
prepare_ios_simulator
Boot an iOS/tvOS simulator, download WebDriverAgent if not cached, and install/launch WDA in a single call.
appium_prepare_ios_real_device
Prepare a real iOS device: first list available .mobileprovision profiles, then download WDA for the chosen UUID, package it as an IPA, and resign it.
appium_session_management
Unified session management: create, attach, detach, delete, list, and select sessions.
appium_mobile_device_control
Control device behavior: lock/unlock the screen, shake the device, or open the notifications panel.
appium_driver_settings
Read or update Appium driver session settings.
appium_context
Manage contexts: list available native and WebView contexts, or switch to a target context.
appium_find_element
Find an element with traditional locator strategies, prioritizing accessibility id, id, and platform-native strategies before xpath.
appium_ai
Opt-in (requires AI_VISION_ENABLED=true): vision-based natural-language element finding that returns a coordinate handle for gesture tools.
appium_gesture
Perform a touch gesture: back, tap, double tap, long press, scroll, swipe, pinch zoom, or scroll until an element appears.
appium_drag_and_drop
Perform drag and drop gestures between elements and/or coordinates.
appium_perform_actions
Execute raw W3C Actions API sequences for custom multi-touch gestures.
appium_set_value
Enter text into an input field.
appium_screenshot
Capture a screenshot of the device.
appium_get_page_source
Retrieve the current page source.
generate_locators
Generate element locators.
appium_screen_recording
Start or stop screen recording as an MP4 file.
appium_app_lifecycle
Manage app lifecycle, including listing apps.
appium_documentation_query
RAG search over the Appium documentation (opt-in, requires the optional package).
appium_skills
Skill-related documentation tooling for Appium (opt-in, requires the optional package).

Setup

  1. Make sure Node.js v22 or higher, npm or yarn, and JDK 8 or higher are installed; install the Android SDK and set ANDROID_HOME for Android testing, and Xcode on macOS for iOS testing.
  2. Add the server to your MCP client config: command npx, args ["appium-mcp@latest"], type stdio, with ANDROID_HOME set in env.
  3. Optionally create capabilities.json and point CAPABILITIES_CONFIG at it; you can also use the Cursor one-click install button, gemini mcp add appium-mcp npx -y appium-mcp@latest, or claude mcp add appium-mcp -- npx -y appium-mcp@latest.
  4. Call select_device first, then create a session to start automating.
claude_desktop_config.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"
      }
    }
  }
}

Fit and risk

Best for

  • Teams doing Android/iOS automation testing with Appium
  • Developers who want to create and debug mobile tests in natural language
  • Engineering teams that need generated test code and Page Object templates
  • Teams running mobile automation in trusted CI environments

Not for

  • Shared or multi-tenant services exposed to untrusted users
  • Environments without Android SDK, Xcode, or a Java toolchain
  • Pure browser or desktop web automation instead of mobile

Required permissions

  • Read access to the local Android SDK and Xcode/simulator setup
  • Access to local mobile devices or emulators through adb or simulator tooling
  • Read/write access to the screenshots and recordings directory (SCREENSHOTS_DIR or the system temp directory)
  • Optional: network access to a remote Appium/WebDriver server (remoteServerUrl)
  • Optional: outbound calls to an external vision model API (AI_VISION_API_BASE_URL and AI_VISION_API_KEY)

Risks and side effects

  • remoteServerUrl is caller-controlled; if it is derived from untrusted input it can reach unintended servers, so restrict destinations with REMOTE_SERVER_URL_ALLOW_REGEX
  • By default the server deletes all MCP-owned Appium sessions when the MCP client disconnects, and transports that drop easily such as httpStream can tear down automation in one go; use APPIUM_MCP_ON_CLIENT_DISCONNECT=skip to keep them
  • Enabling vision element finding sends screenshots to a third-party vision API, which can incur cost and data exposure
  • Persisted session files may contain credentials and sensitive capabilities (created with 0600 permissions)
  • Plugins execute inside the server process, so only trusted files and packages should be loaded

Troubleshooting

  1. Server fails to start complaining about AI_VISION_API_BASE_URL or AI_VISION_API_KEY: AI_VISION_ENABLED=true was set without both API variables
  2. The appium_ai tool is missing: confirm AI_VISION_ENABLED is set to true
  3. Documentation tools are missing: confirm @appium/mcp-documentation is installed and APPIUM_MCP_DOCS_ENABLED is true
  4. Remote server connections are rejected: check REMOTE_SERVER_URL_ALLOW_REGEX and whether the URL contains a query string or fragment
  5. Sessions disappear after the client reconnects: set APPIUM_MCP_ON_CLIENT_DISCONNECT to skip
  6. iOS screen recording fails: verify ffmpeg is installed and on PATH
  7. Responses are too large or slow: set NO_UI=true or NO_UI=1

Use cases

Drive Android or iOS app automation from an AI assistant using natural language
Generate Java/TestNG test code from natural-language descriptions
Run mobile automation in CI with NO_UI mode to save tokens and bandwidth
Use vision models to locate UI elements that resist traditional locators
Query Appium documentation through appium_documentation_query

Supported clients

CursorFull support
Claude CodeFull support
Gemini CLIFull support