MCP Appium

A Model Context Protocol (MCP) integration for Appium, enabling automated mobile app testing through natural language interactions. This project provides a set of tools that allow AI models to interact with mobile applications using Appium's WebDriver protocol.

⚠️ Disclaimer: Most of this code has been generated using Cursor's Agent and AI. Do not expect to find tests or a high quality codebase.

Overview

This project bridges the gap between AI language models and mobile app automation by providing a standardized interface through MCP. It allows AI models to perform various mobile testing operations like finding elements, clicking, taking screenshots, and more.

Prerequisites

• Appium Server running
• Mobile device or emulator connected
• Active Appium session

Installation & Usage

You can run the MCP server using Docker in two ways, or using Node.js in two ways.

If no APPIUM_SESSION_ID is provided, the server will use the first available session.

As an NPM package (recommended)

npm install -g mcp-appium

env APPIUM_SESSION_ID="your-session-id" npx -y mcp-appium

In Cursor:

{
  "mcpServers": {
    "Appium": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-appium"
      ]
    }
  }
}

Using Docker

⚠️ The Appium server must be accessible from the container. Use the environment variable APPIUM_SERVER_URL to specify the URL of the Appium server (host and port). Its default value is http://localhost:4723.

1. Build the image:

docker build -t mcp-appium .

2. Run the container:

Manually

docker run -i -e APPIUM_SERVER_URL=http://host.docker.internal:4723 --network host mcp-appium

In Cursor

{
  "mcpServers": {
    "Appium": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-e",
        "APPIUM_SERVER_URL=http://host.docker.internal:4723",
        "--network",
        "host",
        "mcp-appium"
      ]
    }
  }
}

Using Docker Compose

1. Create a .env file with your configuration:

APPIUM_SESSION_ID=your-session-id

2. Run with docker-compose:

docker-compose up

The --network host flag is used to allow the container to access the Appium server running on your host machine.

Available Tools

1. Find Element (appium_find_element)

Locates an element on the current view of the mobile application.

Input Parameters:

• using (string, required): The strategy to use for finding the element (e.g., class name, id, xpath)
• value (string, required): The value to search for using the specified strategy

2. Find Elements (appium_find_elements)

Locates all elements matching the criteria on the current view of the mobile application.

Input Parameters:

• using (string, required): The strategy to use for finding the elements (e.g., class name, id, xpath)
• value (string, required): The value to search for using the specified strategy

3. Click Element (appium_click_element)

Performs a click action on a specified element.

Input Parameters:

• elementId (string, required): The ID of the element to click (obtained from Find Element)

4. Send Keys (appium_send_keys)

Sends keyboard input to a specified element.

Input Parameters:

• elementId (string, required): The ID of the element to send keys to
• text (string, required): The text to input

5. Take Screenshot (appium_take_screenshot)

Captures a screenshot of the current view and saves it to the Downloads directory.

Input Parameters:

• No parameters required

6. List Sessions (appium_list_sessions)

Lists all active Appium sessions.

Input Parameters:

• No parameters required

7. Get Source (appium_get_source)

Retrieves the XML representation of the current view hierarchy.

Input Parameters:

• No parameters required

8. Scroll (appium_scroll)

Scrolls to specific coordinates on the screen.

Input Parameters:

• x (number, required): X coordinate on the screen
• y (number, required): Y coordinate on the screen

Usage

The tools are designed to be used through the Model Context Protocol (MCP) interface. Each tool can be called with its respective parameters to perform mobile automation tasks.

Error Handling

All tools include proper error handling and will return meaningful error messages if:

• No active Appium session is found
• Element location fails
• Network requests to Appium server fail
• Invalid parameters are provided