MCP Mobile Agent Server - Node.js implementation for mobile device control via ADB
npm install codingbaby-mobileπ€ A powerful MCP (Model Context Protocol) server for mobile device automation through ADB.


- π± 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
Add to your MCP client configuration (e.g., claude_desktop_config.json, Cursor MCP settings, etc.):
``json`
{
"mcpServers": {
"codingbaby-mobile": {
"command": "npx",
"args": ["-y", "codingbaby-mobile@latest"],
"env": {
"ADB_PATH": "/your/adb/path"
}
}
}
}
macOS:
`bash`
brew install android-platform-tools
Linux (Ubuntu/Debian):
`bash`
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/usr/bin/adb
- Linux: or ~/Android/Sdk/platform-tools/adbC:\Android\sdk\platform-tools\adb.exe
- Windows:
Note: On Windows, the ADB executable is adb.exe, while on macOS/Linux it's just adb.
Set ADB Permissions (macOS/Linux):
`bash`
sudo chmod +x /path/to/adb
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)
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
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:
`bash`
# 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)
For better text input support, install an ADB-compatible keyboard:
1. Download ADB Keyboard APK:
`bash`
# 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:
`bash`
# 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
Test your setup with these commands:
`bashCheck device connection
adb devices
Configuration
$3
Configure ADB path in your MCP server configuration:
`json
{
"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.exeAvailable Tools
The server provides 8 powerful tools for mobile device control:
$3
Set the ADB executable path
`json
{
"adbPath": "/path/to/adb"
}
`$3
Take a screenshot of the device
`json
{}
`$3
Tap at specific coordinates
`json
{
"x": 100,
"y": 200
}
`$3
Swipe between two points
`json
{
"x1": 100,
"y1": 200,
"x2": 300,
"y2": 400,
"duration": 500
}
`$3
Type text on the device
`json
{
"text": "Hello World"
}
`$3
Navigate back
`json
{}
`$3
Go to home screen
`json
{}
`$3
Get screen information and device status
`json
{}
`Usage Examples
$3
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
$3
ADB not found:
- Ensure ADB is installed and in your PATH
- Set the correct ADB_PATH in your configuration
Device not detected:
`bash
Check USB debugging is enabled
adb devicesRestart ADB server
adb kill-server
adb start-serverCheck device authorization
adb devices
`Permission denied:
`bash
On Linux/macOS, you might need to add your user to plugdev group
sudo usermod -a -G plugdev $USEROr 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:
`bash
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
``- Android: 4.4+ (API level 19+)
- Node.js: 18.0.0+
- ADB: Latest version recommended
- Node.js >= 18.0.0
- ADB (Android Debug Bridge)
- Android device with USB debugging enabled
- MCP-compatible client (Claude Desktop, Cursor, etc.)
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License - see the LICENSE file for details.
- π Bug Reports: GitHub Issues
- π Documentation: GitHub Wiki
- π¬ Discussions: GitHub Discussions
---
Note: This project is part of the CodingBaby Mobile Agent ecosystem.