appium

This MCP server exposes Appium automation capabilities through the MCP protocol, enabling Claude and other MCP-compatible clients to start and manage Appium sessions, locate and interact with UI elements, and inspect app pages. It supports cross-platform mobile automation (iOS and Android), with session management tools to start, query, and quit sessions, element interaction commands to find, tap, and input text, and page navigation commands to retrieve page sources and perform scrolling. Use the provided MCP endpoints to drive native apps, mobile browsers, or installed apps via Appium's drivers. The server acts as a bridge between MCP requests and Appium's WebDriver protocol, translating generic MCP actions into Appium commands.

Typical workflows involve starting a session with platform details and device information, locating elements using strategies like id, xpath, class_name, or accessibility_id, performing taps or text input, and then retrieving page content or scrolling to reach desired UI regions. This makes it straightforward to script mobile automation tasks from Claude Desktop or other MCP clients, including login flows, navigational checks, and form interactions across both iOS and Android platforms.

Prerequisites

• Node.js 18.1+ (for npx usage)
• Python 3.12+ (as referenced by the project requirements, if the MCP server relies on Python components)
• Appium Server running locally at http://localhost:4723

Installation steps (Option 1: Using npx, Recommended)

1. Install Appium globally (only if you need Appium drivers locally for initial setup):

# Install Appium globally
npm install -g appium

# Install drivers for your platforms (optional if using system Appium setup)
appium driver install xcuitest     # for iOS
appium driver install uiautomator2 # for Android

2. Start Appium server (in a separate terminal, ensure Appium is running on port 4723):

appium server --port 4723

3. Install the MCP server via npx (this repository's MCP server):

npx -y appium-mcp-server@latest

4. Add the MCP server to Claude Desktop (or your MCP client) configuration. Example using the recommended npx approach:

{
  "mcpServers": {
    "appium-mcp-server": {
      "command": "npx",
      "args": ["-y", "appium-mcp-server@latest"]
    }
  }
}

Prerequisites recap and notes:

• Ensure Appium server is up and reachable at http://localhost:4723
• Have the appropriate mobile drivers installed for your target platforms
• Ensure environment variables (e.g., PATH) include Node.js and Appium binaries if started outside npm/npx context

Optional alternative (if you host the MCP server directly):

• Run directly with Node if the project provides a bin/appium-mcp-server.js entry point:

node bin/appium-mcp-server.js

Tips and caveats:

• Keep Appium and its drivers up to date to match iOS/Android platform changes.
• When running on Apple Silicon (M1/M2), if you build or run Python components locally, you may need to rebuild virtual environments to avoid architecture issues.
• Ensure your test devices or simulators are properly configured and accessible to Appium; verify connection with a simple Appium inspector or a sample script first.
• The MCP server translates MCP actions to Appium WebDriver commands; for complex gestures or advanced capabilities, refer to Appium documentation and map MCP actions accordingly (e.g., precise coordinates for taps or multi-touch gestures).
• If you encounter connectivity issues, confirm the MCP server process is running and that Claude has the correct server URL and authentication (if configured).
• Environment variables used by the server (e.g., PYTHONPATH, GEMINI_API_KEY) are optional depending on deployment; document and provide placeholders in your config as needed.