codingbaby-mobile/README.md

MCP Mobile Agent Server - Node.js implementation for mobile device control via ADB

# Mobile Agent MCP Server

**Language**: [English](README.md) | [中文](README_zh.md)

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

[![npm version](https://badge.fury.io/js/codingbaby-mobile.svg)](https://badge.fury.io/js/codingbaby-mobile)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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.):

```json
{
  "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:**
```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](https://developer.android.com/studio/releases/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):**
```bash
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:
   ```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)

### 5. Install ADB Keyboard (Recommended)

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

### 6. Verify Setup

Test your setup with these commands:

```bash
# 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:

```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.exe`

## Available Tools

The server provides 8 powerful tools for mobile device control:

### 1. `mobile_set_adb_path`
Set the ADB executable path
```json
{
  "adbPath": "/path/to/adb"
}
```

### 2. `mobile_screenshot`
Take a screenshot of the device
```json
{}
```

### 3. `mobile_tap`
Tap at specific coordinates
```json
{
  "x": 100,
  "y": 200
}
```

### 4. `mobile_swipe`
Swipe between two points
```json
{
  "x1": 100,
  "y1": 200,
  "x2": 300,
  "y2": 400,
  "duration": 500
}
```

### 5. `mobile_type`
Type text on the device
```json
{
  "text": "Hello World"
}
```

### 6. `mobile_back`
Navigate back
```json
{}
```

### 7. `mobile_home`
Go to home screen
```json
{}
```

### 8. `mobile_get_screen_info`
Get screen information and device status
```json
{}
```

## 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:**
```bash
# Check USB debugging is enabled
adb devices

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

# Check 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 $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:**
```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
```

### 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](LICENSE) file for details.

## Support

- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/KellyGong0301/codingbaby_mobile/issues)
- 📚 **Documentation**: [GitHub Wiki](https://github.com/KellyGong0301/codingbaby_mobile/wiki)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/KellyGong0301/codingbaby_mobile/discussions)

---

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