Appiumium - Appium MCP Server

An MCP (Model Context Protocol) server for mobile and desktop application testing using Appium WebDriver.

Features

This MCP server provides tools for:

• Session Management: Start and end Appium testing sessions
• Element Interaction: Find, click, and type into elements
• Information Retrieval: Get element text and page source
• Screenshots: Capture screenshots during testing
• Gestures: Perform swipe gestures
• Multi-platform: Supports Android, iOS, Windows, and Mac testing

Prerequisites

Before using this MCP server, you need:

1. Node.js (v18 or higher)
2. Appium Server running locally or remotely
3. Platform-specific requirements:
   • Android: Android SDK, Android emulator or real device
   • iOS: Xcode, iOS Simulator or real device (macOS only)
   • Windows/Mac: Applications to test on desktop platforms

Installing Appium Drivers

The project comes with Appium 3.x. Install drivers using:

npx appium driver install uiautomator2  # For Android
npx appium driver install xcuitest      # For iOS
npx appium driver install mac2          # For macOS desktop apps

Then start the Appium server:

npx appium

The server will run on http://localhost:4723 by default.

Installation

npm install
npm run build

GitHub Copilot Agents

This package includes three specialized agents for Appium testing that integrate with GitHub Copilot:

• Test Executor: Execute manual test cases step-by-step with validation
• Test Generator: Generate automated test code from test plans or requirements
• Test Healer: Debug and fix failing Appium tests

Seeding Agents

To use these agents in your repository with GitHub Copilot, run:

npx appiumium seed --loop=copilot

This will copy the agent files to your repository's .github/chatmodes/ directory, making them available for GitHub Copilot to use when assisting with Appium testing tasks.

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "appiumium": {
      "command": "node",
      "args": ["/absolute/path/to/appiumium/build/index.js"]
    }
  }
}

With MCP Inspector

npx @modelcontextprotocol/inspector node build/index.js

Available Tools

1. start_session

Initialize a new Appium session with capabilities.

Parameters:

• platformName (required): Android, iOS, Windows, or Mac
• deviceName (optional): Device name for mobile testing
• app (optional): Path to app or app package/bundle ID
• automationName (optional): Automation framework (UiAutomator2, XCUITest)
• udid (optional): Device UDID for real devices
• appiumServerUrl (optional): Appium server URL (default: http://localhost:4723)

Example:

{
  "platformName": "Android",
  "deviceName": "Pixel_5_API_31",
  "app": "/path/to/app.apk",
  "automationName": "UiAutomator2"
}

2. find_element

Find an element using various selector strategies.

Parameters:

• strategy: id, xpath, accessibility id, class name, android uiautomator, ios predicate string
• selector: Element selector string

3. click_element

Click on an element.

Parameters:

• selector: Element selector (XPath, ID, etc.)

4. send_keys

Type text into an element.

Parameters:

• selector: Element selector
• text: Text to type

5. get_element_text

Get the text content of an element.

Parameters:

• selector: Element selector

6. take_screenshot

Capture a screenshot of the current screen.

7. swipe

Perform a swipe gesture.

Parameters:

• startX: Start X coordinate
• startY: Start Y coordinate
• endX: End X coordinate
• endY: End Y coordinate
• duration: Swipe duration in milliseconds (default: 500)

8. get_page_source

Get the XML page source of the current screen.

9. end_session

End the current Appium session and close the app.

Example Workflows

Testing an Android App

1. Start session:

Use the start_session tool with platformName: Android, app: /path/to/app.apk

2. Find and interact with elements:

Use find_element to locate a button
Use click_element to click it
Use send_keys to enter text in a field

3. Verify and capture:

Use get_element_text to verify text
Use take_screenshot to capture the screen

4. End session:

Use end_session to close the app

Testing an iOS App

Use start_session with platformName: iOS, app: /path/to/app.app, automationName: XCUITest

Troubleshooting

Appium Server Not Running

Ensure Appium server is running:

appium

Driver Not Installed

Install the required driver:

appium driver install uiautomator2  # Android
appium driver install xcuitest      # iOS

Device Not Found

• For Android: Check adb devices
• For iOS: Check Xcode Simulator list
• Use correct deviceName or udid parameter

Session Creation Fails

Check Appium logs for detailed error messages. Common issues:

• App path is incorrect
• Device/emulator is not available
• Capabilities are misconfigured

Development

Build

npm run build

Watch Mode

npm run watch

License

MIT