Appium MCP Claude Android

🚀 MCP Appium - Automated Mobile Testing with Model Context Protocol

MCP Appium provides Appium as an MCP (Model Context Protocol) server, enabling AI agents to automatically control and test mobile devices.

✨ Features

• Automatic Server Startup: Automatically start the Appium server (no GUI required).
• Automatic Device Detection: Automatically detect connected Android devices via adb devices.
• Automatic Configuration: Automatically generate configuration files based on detected device information.
• Flexible Testing: Freely test all apps on the device without being restricted to specific apps.
• MCP Integration: Seamlessly integrate with AI agents such as Claude Code.
• One-Click Installation: Easily install and register with MCP using an automatic installation script.

🚀 Quick Start

1. Installation

Method 1: Clone the repository and install (recommended)

git clone https://github.com/supremehyo/appium-mcp-claude-android.git
cd appium-mcp-claude-android
./install.sh

Method 2: Remote installation (installed in the home directory)

curl -sSL https://raw.githubusercontent.com/supremehyo/appium-mcp-claude-android/main/install-remote.sh | bash
# After installation: cd ~/.mcp-appium

2. Open in Claude Code

# In the installed directory
claude
# Or run Claude Code in the directory by other means

Claude Code automatically detects .mcp.json and requests approval from the MCP server.

3. Usage

In Claude Code:

"Check the connected devices"  → list_devices
"Set up and connect to Appium"  → setup_appium_connection (automatic setup!)
"Show the current screen elements"  → get_screen_elements

For detailed installation instructions, refer to INSTALL.md.

📦 Prerequisites

1. Install Node.js and Appium

# Install Node.js (https://nodejs.org/)

# Install Appium globally
npm install -g appium

# Install the UiAutomator2 driver
appium driver install uiautomator2

2. Install Android SDK and ADB

• Install Android Studio and then install SDK Platform-Tools.
• Or download the standalone Platform-Tools: https://developer.android.com/studio/releases/platform-tools

Set environment variables:

# macOS/Linux (add to .bashrc or .zshrc)
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools

# Windows (add to system environment variables)
ANDROID_HOME=C:\Users\YourName\AppData\Local\Android\Sdk
Path=%Path%;%ANDROID_HOME%\platform-tools

3. Install Python packages

pip install -r requirements.txt

📱 Device Preparation

Real Android Devices

1. Enable USB debugging (in developer options).
2. Connect the device to the computer via USB.
3. Approve debugging permission.
4. Check in the terminal: adb devices

Android Emulators

1. Create and run an emulator using AVD Manager in Android Studio.
2. Check in the terminal: adb devices

💻 Usage

Note: If you have run the installation script in the "Quick Start" section above, the MCP server is already registered.

Check Installation

# Check the list of MCP servers
claude mcp list

# "appium" should be in the list

Basic Workflow

1. Check Device Connection

   Use the list_devices tool
   

2. Automatically Configure and Connect to Appium

   Use the setup_appium_connection tool
   

   This tool automatically performs the following:

   • Start the Appium server.
   • Automatically detect connected devices.
   • Automatically generate configuration files.
   • Connect to the device.

3. Check Screen Elements

   Use the get_screen_elements tool
   

4. Execute Actions

   Perform actions such as tap, input, swipe, etc. using the execute_action tool
   

5. Run Automation Scenarios

   Run natural language scenarios using the run_test_scenario tool
   

🛠️ MCP Tool List

1. setup_appium_connection

Start the Appium server and automatically connect to the device.

Parameters:

• port (optional): Appium server port (default: 4723)

Example:

"Set up Appium and connect to the device"

2. list_devices

Display a list of all connected Android devices.

Example:

"Show the list of connected devices"

3. start_appium_server

Manually start only the Appium server.

Parameters:

• port (optional): Appium server port (default: 4723)

4. stop_appium_server

Stop the running Appium server.

5. get_screen_elements

Get all UI elements on the current screen.

6. execute_action

Execute specific actions on the mobile device.

Supported Actions:

• tap: Tap an element.
• input_text: Input text.
• swipe: Swipe.
• long_press: Long press.
• back: Go back.
• hide_keyboard: Hide the keyboard.
• scroll_down: Scroll down.
• scroll_up: Scroll up.

7. run_test_scenario

Automatically run test scenarios written in natural language.

Examples:

"Open the Settings app and navigate to the Wi-Fi menu"
"Open KakaoTalk and enter 'test' in the search bar"

💡 Example Usage Scenarios

Scenario 1: Basic Setup and Testing

User: "Check the connected devices"
Claude: [Execute list_devices]

User: "Set up and connect to Appium"
Claude: [Execute setup_appium_connection]

User: "Show what's on the current screen"
Claude: [Execute get_screen_elements]

User: "Press the Settings icon"
Claude: [Execute execute_action with tap]

Scenario 2: Automation Testing

User: "Open the Gallery app, select the first photo, and then press the share button"
Claude: [Execute run_test_scenario]

🐞 Troubleshooting

"Appium not found" error

# Check if Appium is installed
appium --version

# If not, install it
npm install -g appium
appium driver install uiautomator2

"No devices found" error

# Check device connection via ADB
adb devices

# If the device is not visible:
# 1. Check if USB debugging is enabled.
# 2. Reconnect the USB cable.
# 3. Restart the emulator.

"Connection refused" error

• Check firewall settings.
• Check if port 4723 is in use: lsof -i :4723 (macOS/Linux).
• Use a different port: Specify the port parameter when calling setup_appium_connection.

📄 Log Checking

Appium server logs are stored in the appium.log file.

📄 License

MIT License