使用说明

📱 Mobile MCP

Model Context Protocol Server for Mobile App Automation

A powerful Model Context Protocol server that enables AI assistants to automate iOS and Android mobile applications using Appium. Perfect for mobile testing, automation, and interaction workflows.

Installation • Quick Start • Documentation • Examples

✨ Features

🤖 Appium Integration: Full Appium 2.0 support for iOS and Android
📱 Cross-Platform: Automate both iOS and Android applications
🛠️ 56 Tools: Comprehensive set of mobile automation tools with platform-specific filtering
🔍 Element Finding: Multiple locator strategies (ID, XPath, Accessibility ID, etc.)
👆 Gestures: Tap, swipe, long press, drag & drop, and other touch interactions
📸 Screenshots: Capture device screenshots
🔧 App Management: Install, remove, launch, and close apps
🌳 Page Source: Get XML hierarchy of the current screen
💾 Session Management: Create and manage automation sessions
🎯 Platform Filtering: Tools automatically filtered based on iOS/Android
📦 Easy Installation: Available as npm package

🔧 Prerequisites

Before using this MCP server, ensure you have the following installed:

Required Software

Node.js (v18 or higher)
```
node --version
```
Appium (will be installed with npm install)

For Android Automation:

Android Studio
Android SDK Platform Tools
Java JDK 8 or higher

Set environment variables:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/tools

For iOS Automation (macOS only):
- Xcode (latest version)
- Xcode Command Line Tools
- Carthage: brew install carthage
- ios-deploy: npm install -g ios-deploy

📦 Installation

Option 1: NPM (Recommended)

Install globally via npm:

npm install -g mcp-mobile-automation

Install Appium drivers:

# For Android
npx appium driver install uiautomator2

# For iOS (macOS only)
npx appium driver install xcuitest

Option 2: From Source

Clone and install:

git clone https://github.com/infinityAutomation/mobile-mcp.git
cd mobile-mcp
npm install

# Install drivers
npx appium driver install uiautomator2
npx appium driver install xcuitest

🚀 Quick Start

1. Configure Your MCP Client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mobile-automation": {
      "command": "npx",
      "args": ["mcp-mobile-automation"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "mobile-automation": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-mobile-automation"]
    }
  }
}

2. Basic Usage

1. Start Appium: "Start the Appium server"
2. Create Session: "Create a session for Android emulator Pixel_6"
3. Automate: "Find the login button and click it"
4. Clean Up: "Delete the session and stop Appium"

⚙️ Configuration

Claude Desktop Configuration

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

NPM Installation:

{
  "mcpServers": {
    "mobile-automation": {
      "command": "npx",
      "args": ["mcp-mobile-automation"]
    }
  }
}

Source Installation:

{
  "mcpServers": {
    "mobile-automation": {
      "command": "node",
      "args": ["/path/to/mobile-mcp/src/index.js"]
    }
  }
}

VS Code Configuration

Location: .vscode/mcp.json in your workspace

NPM Installation:

{
  "servers": {
    "mobile-automation": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-mobile-automation"]
    }
  }
}

Source Installation:

{
  "servers": {
    "mobile-automation": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mobile-mcp/src/index.js"]
    }
  }
}

📚 Available Tools

The server provides 56 comprehensive tools organized into the following categories:

🖥️ Server Management

`start_appium`

Start the Appium server.

port (optional): Port number (default: 4723)
host (optional): Host address (default: localhost)

`stop_appium`

Stop the Appium server.

🔌 Session Management

`create_session`

Create a new automation session.

platformName: "iOS" or "Android"
deviceName: Device/emulator name
app: Path to app file (optional)
appPackage/appActivity: Android app details (optional)
bundleId: iOS bundle identifier (optional)

`delete_session`

End the current automation session.

🔍 Element Interaction (10+ tools)

find_element - Find single element by ID, XPath, etc.
find_elements - Find multiple elements
click_element - Click an element
send_keys - Send text to element
clear_element - Clear element text
get_element_text - Get element text
get_element_attribute - Get element attributes
is_element_displayed - Check visibility
is_element_enabled - Check if enabled
submit_element - Submit a form element

👆 Gestures & Actions (15+ tools)

tap - Tap at coordinates
swipe - Swipe gesture
scroll - Scroll in direction
long_press - Long press gesture
drag_and_drop - Drag element to target
pinch - Pinch gesture
zoom - Zoom gesture
hide_keyboard - Hide on-screen keyboard
rotate_device - Rotate device orientation
And more...

📱 App Management

install_app - Install app on device
remove_app - Remove app from device
launch_app - Launch the app
close_app - Close the app
get_app_state - Check app state
activate_app - Activate app in background
terminate_app - Terminate app

📸 Information & Debugging

take_screenshot - Capture screenshot
get_page_source - Get XML hierarchy
get_device_info - Device information
get_device_time - Device time
get_battery_info - Battery status
get_network_connection - Network status
get_clipboard - Get clipboard content
set_clipboard - Set clipboard content

🤖 Android-Specific Tools

start_activity - Start Android activity
press_keycode - Press hardware keycode
toggle_wifi - Toggle WiFi
toggle_airplane_mode - Toggle airplane mode
open_notifications - Open notification drawer
clear_app - Clear app data

🍎 iOS-Specific Tools

touch_id - Simulate Touch ID
face_id - Simulate Face ID
press_key - Press iOS button (home, volumeUp, volumeDown)

Note: Platform-specific tools are automatically filtered based on your active session (iOS or Android).

💡 Usage Examples

Example 1: Android App Login Flow

💡 Usage Examples

Example 1: Android App Login Flow

User: "Start Appium server on port 4723"
Assistant: [Calls start_appium tool]

User: "Create a session for Android emulator Pixel_6_API_33 with app at /path/to/app.apk"
Assistant: [Calls create_session with platformName: "Android", deviceName: "Pixel_6_API_33", app: "/path/to/app.apk"]

User: "Find the username field by ID 'username_input' and enter 'testuser'"
Assistant: [Calls find_element, then send_keys]

User: "Find password field by ID 'password_input' and enter 'password123'"
Assistant: [Calls find_element, then send_keys]

User: "Click the login button with ID 'login_btn'"
Assistant: [Calls find_element, then click_element]

User: "Take a screenshot"
Assistant: [Calls take_screenshot]

User: "Stop everything"
Assistant: [Calls delete_session, then stop_appium]

Example 2: iOS App Testing

User: "Start Appium and create iOS session for iPhone 14 simulator"
Assistant: [Calls start_appium, then create_session]

User: "Swipe up from bottom"
Assistant: [Calls swipe with appropriate coordinates]

User: "Find all buttons on screen"
Assistant: [Calls find_elements with "class name" and "XCUIElementTypeButton"]

User: "Get the page source to see element hierarchy"
Assistant: [Calls get_page_source]

Example 3: Gesture Automation

User: "Perform long press on element with ID 'menu_item'"
Assistant: [Calls find_element, then long_press]

User: "Drag element 'draggable' to element 'drop_zone'"
Assistant: [Calls find_element for both, then drag_and_drop]

User: "Scroll down on the page"
Assistant: [Calls scroll with direction: "down"]

📱 Device Setup

Android Emulator

Open Android Studio → AVD Manager
Create virtual device (e.g., Pixel 6, API 33)
Start emulator
Verify: adb devices

Android Real Device

Enable Developer Options on device
- Settings → About Phone → Tap "Build Number" 7 times
Enable USB Debugging
- Settings → Developer Options → USB Debugging
Connect via USB and accept prompt
Verify: adb devices

iOS Simulator

Open Xcode → Window → Devices and Simulators
Create/start simulator (e.g., iPhone 14)
Verify: xcrun simctl list devices

iOS Real Device

Connect device via USB
Trust computer on device
Register device in Xcode
Get UDID: idevice_id -l or Xcode → Window → Devices and Simulators

🔧 Troubleshooting

Appium Server Issues

Server won't start:

# Check if port is in use
lsof -i :4723

# Kill process
kill -9 <PID>

# Try different port
# Use port parameter in start_appium

Driver not installed:

# List installed drivers
npx appium driver list

# Install missing driver
npx appium driver install uiautomator2
npx appium driver install xcuitest

Android Issues

App won't launch:

# Verify app package and activity
aapt dump badging app.apk | grep package

# Check device connection
adb devices

# View logs
adb logcat | grep -i error

Device not detected:

# Restart ADB
adb kill-server && adb start-server

# Check USB debugging
adb devices

iOS Issues

App won't launch:

Verify bundle ID matches installed app
Ensure app is signed correctly
Check Developer Certificate is trusted on device

Simulator not responding:

# Reset simulator
xcrun simctl erase all

# Restart Xcode
killall Simulator

Real device connection:

Ensure device is unlocked
Trust computer prompt accepted
Latest Xcode installed
Device registered in Apple Developer account

Element Finding Issues

Element not found:

Use get_page_source to inspect hierarchy
Try different locator strategies:
- id - Fastest, most reliable
- accessibility id - Cross-platform
- xpath - Flexible but slower
- class name - For element types
Add wait/delay for dynamic content
Check if element is in different context (webview)

Wrong element selected:

Use more specific XPath
Combine multiple attributes
Use index for multiple matches

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

Development Setup

git clone https://github.com/infinityAutomation/mobile-mcp.git
cd mobile-mcp
npm install

Running Tests

# Start Appium
npx appium

# In another terminal, run your tests
node src/index.js

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Resources

🙏 Acknowledgments

Built with Model Context Protocol SDK
Powered by Appium
Inspired by the mobile automation community

Made with ❤️ by the Infinity Automation Team

Report Bug • Request Feature • Documentation

使用说明

📱 Mobile MCP

Model Context Protocol Server for Mobile App Automation

✨ Features

📋 Table of Contents

🔧 Prerequisites

Required Software

📦 Installation

Option 1: NPM (Recommended)

Option 2: From Source

🚀 Quick Start

1. Configure Your MCP Client

2. Basic Usage

⚙️ Configuration

📚 Available Tools

start_appium

stop_appium

create_session

delete_session

💡 Usage Examples

Example 1: Android App Login Flow

💡 Usage Examples

Example 1: Android App Login Flow

Example 2: iOS App Testing

Example 3: Gesture Automation

📱 Device Setup

Android Emulator

Android Real Device

iOS Simulator

iOS Real Device

🔧 Troubleshooting

🤝 Contributing

Development Setup

Running Tests

📄 License

📚 Resources

🙏 Acknowledgments

相关 MCP

移动自动化MCP服务器

移动自动化服务器

移动测试自动化工具

移动设备GUI自动化服务器

AI设备操作环境

移动自动化测试工具

`start_appium`

`stop_appium`

`create_session`

`delete_session`