MCP 服务器

MCP Appium Server

A Model Context Protocol (MCP) server that enables mobile app automation using Appium, supporting various device interactions, element operations, and app management through a standardized protocol.

Tools

initialize-appium

Initialize an Appium driver session for mobile automation

save-ui-hierarchy

Save UI hierarchy XML to a file

close-appium

Close the current Appium driver session

appium-screenshot

Take a screenshot using Appium

tap-element

Tap on a UI element identified by a selector

send-keys

Send text input to a UI element

get-page-source

Get the XML representation of the current UI

swipe

Perform a swipe gesture on the screen

wait-for-element

Wait for an element to be visible on screen

extract-locators

Extract element locators from UI XML source

find-by-text

Generate XPath to find element by text

generate-test-script

Generate Appium test script from actions

install-app

Install an Android application APK

take-screenshot

Take a screenshot on an Android device

list-devices

List all connected Android devices

uninstall-app

Uninstall an Android application

list-installed-packages

List all installed packages on an Android device

launch-app

Launch an app on an Android device

execute-adb-command

Execute a custom ADB command

README

MCP Appium Server

A Model Context Protocol (MCP) server implementation for mobile app automation using Appium.

Prerequisites

Node.js (v14 or higher)
Java Development Kit (JDK)
Android SDK (for Android testing)
Xcode (for iOS testing, macOS only)
Appium Server
Android device or emulator / iOS device or simulator

Setup

Install dependencies:

npm install

Install and start Appium server:

npm install -g appium
appium

Set up Android device/emulator:
- Enable Developer Options on your Android device
- Enable USB Debugging
- Connect device via USB or start an emulator
- Verify device is connected using adb devices

Running Tests

Build the project:

npm run build

Start the MCP server:

npm run dev

In a new terminal, run the test:

npm test

Test Configuration

The example test uses the Android Settings app as a demo. To test your own app:

Edit examples/appium-test.ts:
- Update deviceName to match your device
- Set app path to your APK file, or
- Update appPackage and appActivity for an installed app
Common capabilities configuration:

const capabilities: AppiumCapabilities = {
    platformName: 'Android',
    deviceName: 'YOUR_DEVICE_NAME',
    automationName: 'UiAutomator2',
    // For installing and testing an APK:
    app: './path/to/your/app.apk',
    // OR for testing an installed app:
    appPackage: 'your.app.package',
    appActivity: '.MainActivity',
    noReset: true
};

Available Actions

The MCP server supports various Appium actions:

Element Interactions:
- Find elements
- Tap/click
- Type text
- Scroll to element
- Long press
App Management:
- Launch/close app
- Reset app
- Get current package/activity
Device Controls:
- Screen orientation
- Keyboard handling
- Device lock/unlock
- Screenshots
- Battery info
Advanced Features:
- Context switching (Native/WebView)
- File operations
- Notifications
- Custom gestures

Troubleshooting

Device not found:
- Check adb devices output
- Verify USB debugging is enabled
- Try reconnecting the device
App not installing:
- Verify APK path is correct
- Check device has enough storage
- Ensure app is signed for debug
Elements not found:
- Use Appium Inspector to verify selectors
- Check if elements are visible on screen
- Try different locator strategies
Connection issues:
- Verify Appium server is running
- Check port conflicts
- Ensure correct capabilities are set