Mobile Agent MCP Server

Language: English | 中文

🤖 A powerful MCP (Model Context Protocol) server for mobile device automation through ADB.

Features

• 📱 Mobile Device Control: Control Android devices remotely via ADB
• 🖼️ Screenshot Capture: Take and process device screenshots
• 👆 Touch Interactions: Tap, swipe, and gesture controls
• ⌨️ Text Input: Type text and send key commands
• 🔄 Navigation: Back, home, and app navigation
• 📊 Device Info: Get screen resolution and device status

Quick Start

MCP Configuration

Add to your MCP client configuration (e.g., claude_desktop_config.json, Cursor MCP settings, etc.):

{
  "mcpServers": {
    "codingbaby-mobile": {
      "command": "npx",
      "args": ["-y", "codingbaby-mobile@latest"],
      "env": {
        "ADB_PATH": "/your/adb/path"
      }
    }
  }
}

Installation and Setup

1. Install ADB (Android Debug Bridge)

macOS:

brew install android-platform-tools

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install android-tools-adb android-tools-fastboot

Windows: Download from Android SDK Platform Tools

Common ADB Paths:

• macOS: /usr/local/bin/adb or ~/Library/Android/sdk/platform-tools/adb
• Linux: /usr/bin/adb or ~/Android/Sdk/platform-tools/adb
• Windows: C:\Android\sdk\platform-tools\adb.exe

Note: On Windows, the ADB executable is adb.exe, while on macOS/Linux it's just adb.

Set ADB Permissions (macOS/Linux):

sudo chmod +x /path/to/adb

2. Enable Android Developer Options

1. Go to Settings > About phone
2. Tap Build number 7 times until "You are now a developer!" appears
3. Go back to Settings > Developer options (or System > Developer options)

3. Enable USB Debugging

1. In Developer options, enable:

   • ✅ USB debugging
   • ✅ Stay awake (keeps screen on while charging)
   • ✅ USB debugging (Security settings) (if available)

2. For HyperOS/MIUI systems: Also enable:

   • ✅ USB debugging (Security settings) (required for HyperOS)

3. For better compatibility, also enable:

   • ✅ OEM unlocking (if you trust this computer)
   • ✅ Disable adb authorization timeout

4. Connect and Authorize Device

1. Connect your Android device via USB
2. Set USB mode to File Transfer (MTP) or PTP (not "Charge only")
3. Run ADB to check connection:

   # Test connection
   /path/to/adb devices
      
   # Examples:
   # Windows: C:\Android\sdk\platform-tools\adb.exe devices
   # macOS/Linux: /usr/local/bin/adb devices

4. First time: A popup will appear on your device asking "Allow USB debugging?"
   • ✅ Check "Always allow from this computer"
   • Tap OK
5. Verify connection: The output should show your device (not empty)

5. Install ADB Keyboard (Recommended)

For better text input support, install an ADB-compatible keyboard:

1. Download ADB Keyboard APK:

   # Method 1: Download from GitHub releases
   wget https://github.com/senzhk/ADBKeyBoard/releases/download/v2.0/AdbKeyboard.apk
   adb install AdbKeyboard.apk
      
   # Method 2: Direct download link
   wget https://github.com/senzhk/ADBKeyBoard/raw/master/ADBKeyboard.apk
   adb install ADBKeyboard.apk

2. Enable ADB Keyboard:

   # Enable the keyboard
   adb shell ime enable com.android.adbkeyboard/.AdbIME
      
   # Set as default input method
   adb shell ime set com.android.adbkeyboard/.AdbIME

3. Manual Setup (Alternative):

   • Install the ADB Keyboard APK on your device
   • Go to Settings > System > Languages & input > Virtual keyboard
   • Add ADB Keyboard to enabled keyboards
   • Switch to ADB Keyboard as default input method

6. Verify Setup

Test your setup with these commands:

# Check device connection
adb devices

# Test screenshot
adb shell screencap -p /sdcard/test.png
adb pull /sdcard/test.png

# Test input
adb shell input tap 100 100
adb shell input text "Hello World"

Configuration

ADB Path Setup

Configure ADB path in your MCP server configuration:

{
  "mcpServers": {
    "codingbaby-mobile": {
      "command": "npx",
      "args": ["-y", "codingbaby-mobile@latest"],
      "env": {
        "ADB_PATH": "/your/adb/path"
      }
    }
  }
}

Replace /your/adb/path with the actual path to ADB on your system:

• macOS: /usr/local/bin/adb or ~/Library/Android/sdk/platform-tools/adb
• Linux: /usr/bin/adb or ~/Android/Sdk/platform-tools/adb
• Windows: C:\Android\sdk\platform-tools\adb.exe

Available Tools

The server provides 8 powerful tools for mobile device control:

1. mobile_set_adb_path

Set the ADB executable path

{
  "adbPath": "/path/to/adb"
}

2. mobile_screenshot

Take a screenshot of the device

{}

3. mobile_tap

Tap at specific coordinates

{
  "x": 100,
  "y": 200
}

4. mobile_swipe

Swipe between two points

{
  "x1": 100,
  "y1": 200,
  "x2": 300,
  "y2": 400,
  "duration": 500
}

5. mobile_type

Type text on the device

{
  "text": "Hello World"
}

6. mobile_back

Navigate back

{}

7. mobile_home

Go to home screen

{}

8. mobile_get_screen_info

Get screen information and device status

{}

Usage Examples

With MCP-Compatible IDEs

Once configured in your MCP client, you can use natural language to control your mobile device:

• "Take a screenshot of my phone"
• "Tap on the search button at coordinates (100, 200)"
• "Swipe from left to right to navigate"
• "Type 'Hello World' in the text field"
• "Go back to the previous screen"

Troubleshooting

Common Issues

ADB not found:

• Ensure ADB is installed and in your PATH
• Set the correct ADB_PATH in your configuration

Device not detected:

# Check USB debugging is enabled
adb devices

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

# Check device authorization
adb devices

Permission denied:

# On Linux/macOS, you might need to add your user to plugdev group
sudo usermod -a -G plugdev $USER

# Or run with proper permissions
sudo adb devices

Text input not working:

• Install and enable ADB Keyboard (see setup instructions above)
• Some Android versions have restrictions on text input via ADB
• Try switching input methods manually on the device

Screenshots failing:

# Check device screen is on and unlocked
adb shell dumpsys power | grep "Display Power"

# Test manual screenshot
adb shell screencap -p /sdcard/test.png
adb pull /sdcard/test.png

Compatibility

• Android: 4.4+ (API level 19+)
• Node.js: 18.0.0+
• ADB: Latest version recommended

Requirements

• Node.js >= 18.0.0
• ADB (Android Debug Bridge)
• Android device with USB debugging enabled
• MCP-compatible client (Claude Desktop, Cursor, etc.)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Support

• 🐛 Bug Reports: GitHub Issues
• 📚 Documentation: GitHub Wiki
• 💬 Discussions: GitHub Discussions

Note: This project is part of the CodingBaby Mobile Agent ecosystem.