appium‑mcp – AI‑enhanced Appium server for mobile test automation

What it is – A Node‑JS‑based MCP (Model Context Protocol) server that sits on top of the standard Appium automation framework. It exposes the usual Appium capabilities (Android UiAutomator2, iOS XCUITest, etc.) and adds AI‑driven helpers that let you interact with a device using natural‑language descriptions, generate locators automatically, and even produce Java/TestNG test code from plain English.

Core capabilities (as described in the README)

Category	What you get
Cross‑platform mobile automation	Works with Android and iOS devices (real devices, emulators, simulators) using the bundled Appium drivers.
AI‑powered element finding	A tool (`appium_ai`) that sends a screenshot to a configurable vision model (OpenAI‑compatible) and returns the UI element that matches a natural‑language query.
Intelligent locator generation	Generates robust selectors (XPath, accessibility ID, etc.) based on priority rules, reducing flaky tests.
Automated test generation	Turns a natural‑language test description into Java/TestNG code that uses the Page Object Model.
Session management	Creates, attaches to, and cleans up Appium sessions via simple MCP commands; supports both embedded local drivers and remote WebDriver/Appium servers.
Multilingual support	The AI layer can understand several languages (English, Spanish, Chinese, Japanese, Korean, …).
Observability	Optional OpenTelemetry tracing, structured “evidence” records for each action, and configurable screenshot storage.
Extensible plugin API	Allows developers to add custom tools or replace existing ones.

Typical workflow

Install the server (npx appium-mcp@latest) and add it to your IDE’s MCP configuration (Cursor, Gemini CLI, Claude Code, etc.).
Set environment variables – at minimum ANDROID_HOME (or iOS tooling on macOS) and optionally CAPABILITIES_CONFIG pointing to a JSON file that describes your devices.
Start a session – either let the server launch a local driver (action=create) or point it at an existing remote Appium server (remoteServerUrl).
Ask the AI – send a natural‑language request like “tap the Login button” or “find the field labelled Email”. The server uses the vision model (configured via AI_VISION_* variables) to locate the element and performs the action.
Generate code – give a description such as “verify that the welcome screen shows the user’s name after login” and receive ready‑to‑run Java/TestNG code with a Page Object skeleton.
Optional tracing – enable OpenTelemetry (APPIUM_MCP_OTEL_ENABLED=true) to collect spans for each tool call, useful for CI debugging.

Installation & quick start (from the README)

{
  "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 you can click the one‑click install badge to add the server automatically.
With Gemini CLI: gemini mcp add appium-mcp npx -y appium-mcp@latest.
With Claude Code CLI: claude mcp add appium-mcp -- npx -y appium-mcp@latest.

Configuration highlights

AI vision – enable with AI_VISION_ENABLED=true and provide AI_VISION_API_BASE_URL and AI_VISION_API_KEY. The default model is Qwen3-VL-235B-A22B-Instruct.
Documentation tools – opt‑in via APPIUM_MCP_DOCS_ENABLED=true; requires the optional @appium/mcp-documentation package.
OpenTelemetry – toggle with APPIUM_MCP_OTEL_ENABLED; configure standard OTEL_* variables for exporter endpoint, service name, etc.
Session cleanup – controlled by APPIUM_MCP_ON_CLIENT_DISCONNECT (delete_all or skip).
Evidence records – set APPIUM_MCP_EVIDENCE=true to attach a structured JSON block to each element‑find or gesture response, aiding CI diagnostics.

Who might use it?

QA engineers who want to write mobile tests faster by speaking to an assistant instead of hand‑crafting selectors.
Developers building CI pipelines that need reliable, AI‑augmented element location and automatic test scaffolding.
Teams adopting LLM‑driven development tools (Cursor, Claude, Gemini) and looking for a ready‑made MCP server that integrates with those IDEs.
Researchers exploring vision‑based UI interaction on mobile devices, since the server can be pointed at any OpenAI‑compatible vision endpoint.

Limitations & requirements (as per the README)

Requires Node 22+, Java 8+, Android SDK (for Android) and Xcode (for iOS on macOS).
The AI vision feature only works when the required API endpoint and key are supplied; otherwise the appium_ai tool is not registered.
Only one active Appium session is kept per server process; concurrent sessions need separate server instances.
The “general” platform mode lets you pass arbitrary capability sets to a remote Appium server, but local embedded drivers are limited to Android and iOS.

Bottom line

appium-mcp is a genuine software project that extends the well‑known Appium automation stack with AI‑driven capabilities (natural‑language element location, auto‑generated test code, multilingual support) and integrates cleanly with modern LLM‑centric IDEs via the MCP protocol. It is firmly in the AI‑augmented mobile testing space rather than a simple tutorial or link collection.

appium/appium-mcp