README.md•11.1 kB
# Android MCP Server
A Model Context Protocol (MCP) server that provides comprehensive Android device control capabilities via ADB (Android Debug Bridge), featuring UI automation, form filling, and ultra-fast video streaming.
<a href="https://glama.ai/mcp/servers/@jduartedj/android-mcp-server">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@jduartedj/android-mcp-server/badge" alt="Android Server MCP server" />
</a>
## Features
- 📸 **Screenshots**: Capture screenshots from Android devices
- 👆 **Touch & Long Press**: Simulate touch events and long-press gestures with variable duration
- 👉 **Swipe**: Perform swipe gestures between coordinates
- 🚀 **App Management**: Launch apps and list installed packages
- 🔌 **ADB Integration**: Direct integration with Android Debug Bridge
- ⚡ **Auto-Download**: Automatically downloads ADB from official Android sources if not found
## Prerequisites
- Node.js 18 or higher
- Android device connected via USB with USB debugging enabled, or emulator running
**Note:** ADB (Android Debug Bridge) is optional - if not found in your system PATH, the server will automatically download it from official Android sources on first use.
## Quick Start
1. **Clone and Build**
```bash
git clone https://github.com/jduartedj/android-mcp-server.git
cd android-mcp-server
npm install
npm run build
```
2. **Test the Server**
```bash
node dist/index.js
```
The server will start and automatically download ADB if needed.
3. **Add to VS Code** (see [VS Code Integration](#vs-code-integration) below)
## Installation
```bash
npm install
npm run build
```
## Usage
### Running the Server Standalone
```bash
node dist/index.js
```
### Configuration
The server supports the following environment variables:
- `ADB_PATH`: Custom path to ADB executable (default: uses system PATH)
- `DEVICE_SERIAL`: Specific device serial number to target (default: first available device)
## VS Code Integration
### Adding to VS Code GitHub Copilot
To use this MCP server with GitHub Copilot in VS Code:
1. **Open VS Code Settings** (Ctrl+, or Cmd+,)
2. **Search for MCP** or navigate to: `GitHub Copilot > Chat > MCP Servers`
3. **Edit the MCP configuration** by clicking "Edit in settings.json"
4. **Add the Android MCP Server** to your configuration:
```json
{
"github.copilot.chat.mcp.servers": {
"android-mcp-server": {
"command": "node",
"args": ["F:\\android-mcp-server\\dist\\index.js"],
"env": {
"ADB_PATH": "",
"DEVICE_SERIAL": ""
}
}
}
}
```
**Note:** Replace `F:\\android-mcp-server\\dist\\index.js` with the actual absolute path to your `dist/index.js` file. Use double backslashes on Windows.
5. **Alternative: Using npx** (if published to npm):
```json
{
"github.copilot.chat.mcp.servers": {
"android-mcp-server": {
"command": "npx",
"args": ["-y", "android-mcp-server"]
}
}
}
```
6. **Reload VS Code** or restart the GitHub Copilot extension
### Verifying the Integration
After adding the server:
1. Open GitHub Copilot Chat in VS Code
2. Type `@workspace` and you should see the Android MCP tools available
3. Try asking: "Take a screenshot of my Android device"
4. Copilot will use the `android_screenshot` tool to capture the screen
### Example Prompts for Copilot
Once integrated, you can ask GitHub Copilot:
- "Take a screenshot of my Android device"
- "Tap at coordinates 500, 1000 on my phone"
- "Swipe up on my Android screen"
- "List all installed apps on my device"
- "Launch the Chrome app"
- "Find the login button and click it"
- "Fill in the email field with user@example.com"
- "Dump the UI hierarchy of the current screen"
- "Long press on the menu button"
- "Scroll down in the settings list"
- "Double-click on the text field"
- "Toggle the enable notifications checkbox"
- "Wait for the loading indicator to disappear"
- "Fill out the registration form with sample data"
- "Take a screenshot using Scrcpy for faster capture"
## Common Use Cases
### 1. App Testing & Navigation
Use touch, swipe, and screenshots to test app navigation:
```
1. Take screenshot to see current state
2. Tap on buttons or links using coordinates
3. Swipe to navigate or scroll through screens
4. Take screenshot to verify results
```
### 2. Automated App Launching
Launch specific apps and verify they start:
```
1. List packages to find app you want to launch
2. Launch app by package name
3. Wait a moment for app to start
4. Take screenshot to verify launch
```
### 3. Multi-Device Automation
Use `deviceSerial` parameter to target specific devices:
```
1. List connected devices via ADB
2. Specify device serial for each tool call
3. Automate actions on multiple devices in parallel
4. Useful for device farms and testing labs
```
### 4. App Discovery
List and search for installed apps:
```
1. List all packages (potentially 100+)
2. Filter packages by name (e.g., "google", "com.example")
3. Launch apps by package name
4. Perfect for discovering available apps on the device
```
### 5. Screenshots for Documentation
Capture application UI for documentation or bug reports:
```
1. Navigate to screen you want to capture
2. Take screenshot and save to file
3. Screenshot can be stored for later analysis or included in reports
```
## All 5 MCP Tools
### 1. `android_screenshot`
Capture a screenshot from the Android device.
**Parameters:**
- `outputPath` (optional): Local path to save the screenshot. If not provided, returns base64 encoded image.
- `deviceSerial` (optional): Target specific device by serial number
**Example:**
```json
{
"name": "android_screenshot",
"arguments": {
"outputPath": "./screenshot.png"
}
}
```
### 2. `android_touch`
Simulate a touch event at specific screen coordinates. Supports both quick taps and long presses.
**Parameters:**
- `x` (required): X coordinate
- `y` (required): Y coordinate
- `duration` (optional): Touch duration in milliseconds (default: 100ms for tap, >100ms for long press)
- `deviceSerial` (optional): Target specific device by serial number
**Example - Quick Tap:**
```json
{
"name": "android_touch",
"arguments": { "x": 500, "y": 1000, "duration": 100 }
}
```
**Example - Long Press:**
```json
{
"name": "android_touch",
"arguments": { "x": 500, "y": 1000, "duration": 2000 }
}
```
### 3. `android_swipe`
Perform a swipe gesture between two coordinates.
**Parameters:**
- `startX` (required): Starting X coordinate
- `startY` (required): Starting Y coordinate
- `endX` (required): Ending X coordinate
- `endY` (required): Ending Y coordinate
- `duration` (optional): Swipe duration in milliseconds (default: 300)
- `deviceSerial` (optional): Target specific device by serial number
**Example:**
```json
{
"name": "android_swipe",
"arguments": {
"startX": 500, "startY": 1500, "endX": 500, "endY": 500, "duration": 300
}
}
```
### 4. `android_launch_app`
Launch an Android app by package name.
**Parameters:**
- `packageName` (required): Package name of the app (e.g., com.example.app, com.google.android.apps.maps)
- `deviceSerial` (optional): Target specific device by serial number
**Example:**
```json
{
"name": "android_launch_app",
"arguments": { "packageName": "com.example.app" }
}
```
### 5. `android_list_packages`
List installed packages on the Android device with optional filtering.
**Parameters:**
- `filter` (optional): Search filter for package names (case-insensitive)
- `deviceSerial` (optional): Target specific device by serial number
**Example - List All Packages:**
```json
{
"name": "android_list_packages",
"arguments": {}
}
```
**Example - Filter Packages:**
```json
{
"name": "android_list_packages",
"arguments": { "filter": "google" }
}
```
## Tool Performance Comparison
| Tool | Purpose | Speed | Notes |
|------|---------|-------|-------|
| `android_screenshot` | Capture screen | ~1-2s | File storage or base64 return |
| `android_touch` | Tap or long press | Immediate | Variable duration support |
| `android_swipe` | Swipe gesture | Immediate | Directional scrolling |
| `android_launch_app` | Start app | ~1-2s | By package name |
| `android_list_packages` | Find apps | Medium | Full or filtered list |
## ADB Setup
### Automatic Installation
The server will automatically download and install ADB from official Android sources if it's not found on your system. The downloaded ADB will be stored in `~/.android-mcp-server/platform-tools/`.
### Manual Installation (Optional)
**Windows:**
```bash
choco install adb
```
**macOS:**
```bash
brew install android-platform-tools
```
**Linux:**
```bash
sudo apt-get install android-tools-adb
```
### Enabling USB Debugging on Android
1. Go to **Settings** → **About Phone**
2. Tap **Build Number** 7 times to enable Developer Options
3. Go to **Settings** → **Developer Options**
4. Enable **USB Debugging**
5. Connect device via USB and accept the debugging prompt
### Verify Connection
```bash
adb devices
```
## Troubleshooting
| Issue | Solution |
|-------|----------|
| "No Android devices found" | Ensure device is connected via USB and USB debugging is enabled. Run `adb devices` to verify. |
| UIAutomator element not found | Use `android_uiautomator_dump` to inspect the XML and verify the resource ID exists. |
| WebView form input not working | Verify the placeholder text, CSS selector, or index is correct. |
| Scrcpy stream won't start | Ensure device has USB debugging enabled and Scrcpy is properly initialized. |
| "ADB not found" error | Run the server once to auto-download ADB, or manually install platform-tools. |
| Touch coordinates not working | Verify coordinates are within screen bounds. |
| App launch fails | Verify package name is correct using `android_list_packages`. |
## Advanced Usage Patterns
### Basic App Testing Workflow
1. Take screenshot to see current state
2. Identify coordinates of elements from screenshot
3. Tap or swipe to interact with app
4. Take screenshot to verify results
5. Repeat until test is complete
### Multi-Device Testing
1. Get list of all connected devices
2. Specify device serial in each tool call
3. Execute same actions on multiple devices simultaneously
4. Compare results across devices
### Continuous Screen Monitoring
1. Loop: Take screenshot → analyze → take action
2. Great for monitoring app state changes
3. Can be combined with time-based intervals
## Architecture
The server uses the Model Context Protocol to expose Android device control capabilities:
- **ADB Wrapper**: Device communication and command execution, auto-downloads ADB if needed
- **Tool Handlers**: Implements screenshot, touch, swipe, app management operations
- **MCP Server**: Exposes all tools via Model Context Protocol for agent use
### Supported Android Versions
- Android 5.0+ (API Level 21+)
## Development
```bash
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run watch
```
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.