# Enhanced ADB MCP Server for Flutter/Android Development

[![PyPI version](https://badge.fury.io/py/r-adb-mcp-server.svg)](https://badge.fury.io/py/r-adb-mcp-server)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A comprehensive MCP server for controlling Android devices via ADB, specifically designed for Flutter development, UI testing, and visual QA workflows.

## Quick Start

```bash
# Install from PyPI
pip install r-adb-mcp-server

# Or run directly with uvx (no installation needed)
uvx r-adb-mcp-server
```

**Note:** Both the package name and command are `r-adb-mcp-server`.

Then add to your MCP client configuration (Claude Desktop, Cursor, etc.) - see [Configuration](#configuration) section below.

## Features

### 📱 Device Management
- List connected devices with details
- Get comprehensive device info (model, Android version, battery, etc.)
- Screen specifications with DP calculations

### 📸 Visual Capture
- Screenshots (base64 or file)
- Screen recording with start/stop control
- Capture with metadata for Figma comparison

### 🔍 UI Inspection
- Full UI hierarchy dump (XML)
- Find elements by text or resource ID
- Get all clickable elements with coordinates
- Extract all visible text for verification

### 🎯 Input & Interaction
- Tap, double-tap, long-press
- Swipe and scroll (up/down/to-text)
- Text input and clear
- Key events (HOME, BACK, ENTER, etc.)
- Tap elements by text or ID

### 📦 App Management
- Launch/stop/clear apps
- Install/uninstall APKs
- List packages with filtering
- Get current activity
- App info (version, install date, etc.)

### 🐛 Debugging & Logs
- Logcat with filtering (tag, level, package)
- Flutter-specific logs
- Crash logs extraction
- ANR traces

### ⚡ Performance Profiling
- Memory usage per app
- CPU monitoring
- GPU rendering info
- Frame stats for jank detection
- Battery statistics

### 🌐 Network Control
- Network info (WiFi status, IP)
- Toggle WiFi/Airplane mode
- Set/clear HTTP proxy

### ⚙️ Developer Options
- Animation scale (speed up tests)
- Show taps (for recordings)
- Show layout bounds
- Screen rotation control
- Change resolution/density

### ♿ Accessibility Testing
- Font scale adjustment
- TalkBack toggle
- High contrast mode
- Color inversion

### 📍 Emulator Features
- GPS location spoofing
- Simulate SMS/calls

## Prerequisites

1. **ADB installed** and in your PATH
   ```bash
   adb version
   ```

2. **Android device/emulator** connected with USB debugging enabled
   ```bash
   adb devices
   ```

3. **Python 3.10+** and optionally `uv` for running with `uvx`

   To install `uv` (optional, for `uvx` command):
   ```bash
   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh

   # Or with Homebrew (macOS)
   brew install uv

   # Or with pip
   pip install uv
   ```

## Installation

### From PyPI (Recommended)

```bash
# Install globally with pip
pip install r-adb-mcp-server

# Or use with uvx (no installation needed)
uvx r-adb-mcp-server
```

### From Source

```bash
cd adb-mcp-server

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .
```

## Configuration

### Claude Desktop

**Using installed package (recommended):**

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "adb": {
      "command": "uvx",
      "args": ["r-adb-mcp-server"]
    }
  }
}
```

**Or if installed with pip:**

```json
{
  "mcpServers": {
    "adb": {
      "command": "r-adb-mcp-server"
    }
  }
}
```

**Using from source:**

```json
{
  "mcpServers": {
    "adb": {
      "command": "uv",
      "args": ["--directory", "/path/to/adb-mcp-server", "run", "python", "src/adb_mcp_server/server.py"]
    }
  }
}
```

### Cursor IDE

Add to `.cursor/mcp.json`:

**Using installed package (recommended):**

```json
{
  "mcpServers": {
    "adb": {
      "command": "uvx",
      "args": ["r-adb-mcp-server"]
    }
  }
}
```

**Using from source:**

```json
{
  "mcpServers": {
    "adb": {
      "command": "uv",
      "args": ["--directory", "/path/to/adb-mcp-server", "run", "python", "src/adb_mcp_server/server.py"]
    }
  }
}
```

### Claude Code

**Using installed package (recommended):**

```bash
claude mcp add adb -- uvx r-adb-mcp-server
```

**Using from source:**

```bash
claude mcp add adb -- uv --directory /path/to/adb-mcp-server run python src/adb_mcp_server/server.py
```

### GitHub Copilot

**Using installed package (recommended):**

Add to your VS Code settings (`.vscode/settings.json` or User Settings):

```json
{
  "github.copilot.chat.mcp.servers": {
    "adb": {
      "command": "uvx",
      "args": ["r-adb-mcp-server"]
    }
  }
}
```

**Or if installed with pip:**

```json
{
  "github.copilot.chat.mcp.servers": {
    "adb": {
      "command": "r-adb-mcp-server"
    }
  }
}
```

**Using from source:**

```json
{
  "github.copilot.chat.mcp.servers": {
    "adb": {
      "command": "uv",
      "args": ["--directory", "/path/to/adb-mcp-server", "run", "python", "src/adb_mcp_server/server.py"]
    }
  }
}
```

**Note:** Make sure you have GitHub Copilot Chat extension installed and MCP support enabled in VS Code.

## Available Tools (60+)

### Device Management
| Tool | Description |
|------|-------------|
| `list_devices()` | List all connected devices |
| `get_device_info()` | Comprehensive device details |
| `get_screen_specs()` | Screen size, density, DP values |

### Visual Capture
| Tool | Description |
|------|-------------|
| `screenshot()` | Capture as base64 PNG |
| `screenshot_to_file(filename)` | Save screenshot to file |
| `start_screen_record(duration, filename)` | Start recording (max 180s) |
| `stop_screen_record()` | Stop recording |
| `pull_recordings(local_dir)` | Download recordings |
| `capture_screen_for_comparison(name)` | Screenshot with metadata |

### UI Inspection
| Tool | Description |
|------|-------------|
| `get_ui_hierarchy()` | Full UI tree as XML |
| `get_clickable_elements()` | All tappable elements with coordinates |
| `find_element_by_text(text)` | Find by text content |
| `find_element_by_id(resource_id)` | Find by resource ID |
| `get_all_text_on_screen()` | Extract all visible text |

### Input & Interaction
| Tool | Description |
|------|-------------|
| `tap(x, y)` | Tap at coordinates |
| `tap_element(text, resource_id)` | Tap by element identifier |
| `double_tap(x, y)` | Double tap |
| `long_press(x, y, duration)` | Long press |
| `swipe(x1, y1, x2, y2, duration)` | Swipe gesture |
| `scroll_down()` / `scroll_up()` | Scroll screen |
| `scroll_to_text(text)` | Scroll until text visible |
| `input_text(text)` | Type text |
| `clear_text_field(length)` | Clear current field |
| `press_key(keycode)` | Press any key |
| `press_back()` / `press_home()` | Navigation buttons |

### App Management
| Tool | Description |
|------|-------------|
| `get_current_activity()` | Current foreground app |
| `launch_app(package)` | Launch by package name |
| `launch_activity(package, activity)` | Launch specific activity |
| `force_stop_app(package)` | Force stop app |
| `clear_app_data(package)` | Clear app data |
| `list_packages(filter, include_system)` | List installed apps |
| `get_app_info(package)` | App details |
| `install_apk(path)` | Install APK |
| `uninstall_app(package)` | Uninstall app |

### Debugging & Logs
| Tool | Description |
|------|-------------|
| `get_logcat(lines, filter_tag, level)` | Get logs |
| `clear_logcat()` | Clear log buffer |
| `get_flutter_logs(lines)` | Flutter-specific logs |
| `get_crash_logs(package)` | Crash/exception logs |
| `get_anr_traces()` | ANR traces |

### Performance
| Tool | Description |
|------|-------------|
| `get_memory_info(package)` | Memory usage |
| `get_cpu_info()` | CPU usage |
| `get_battery_stats()` | Battery details |
| `get_gpu_info()` | GPU rendering info |
| `get_frame_stats(package)` | Frame timing stats |

### Network
| Tool | Description |
|------|-------------|
| `get_network_info()` | WiFi status, IP |
| `toggle_wifi(enable)` | Enable/disable WiFi |
| `toggle_airplane_mode(enable)` | Toggle airplane mode |
| `set_proxy(host, port)` | Set HTTP proxy |
| `clear_proxy()` | Clear proxy |

### Developer Options
| Tool | Description |
|------|-------------|
| `toggle_show_taps(enable)` | Visual tap feedback |
| `toggle_show_layout_bounds(enable)` | Show layout bounds |
| `set_animation_scale(scale)` | Animation speed (0-1) |
| `rotate_screen(orientation)` | portrait/landscape/auto |
| `change_screen_size(w, h)` | Override resolution |
| `reset_screen_size()` | Reset to default |
| `change_density(dpi)` | Override DPI |
| `reset_density()` | Reset to default |

### Accessibility
| Tool | Description |
|------|-------------|
| `set_font_scale(scale)` | System font size |
| `toggle_talkback(enable)` | Screen reader |
| `toggle_high_contrast(enable)` | High contrast text |
| `toggle_color_inversion(enable)` | Invert colors |

### Files & Shell
| Tool | Description |
|------|-------------|
| `push_file(local, remote)` | Copy to device |
| `pull_file(remote, local)` | Copy from device |
| `list_files(path)` | List directory |
| `read_file(path)` | Read text file |
| `shell_command(cmd)` | Run any shell command |
| `reboot_device(mode)` | Reboot device |

### Emulator Only
| Tool | Description |
|------|-------------|
| `set_location(lat, lng)` | Fake GPS location |
| `send_sms(number, message)` | Simulate SMS |
| `simulate_call(number)` | Simulate incoming call |

## Example Prompts

### Basic Usage
- "Take a screenshot of my phone"
- "What's the current screen resolution and density?"
- "List all installed apps containing 'flutter'"
- "What's currently on screen? Get all the text"

### UI Testing
- "Find the login button and tap it"
- "Scroll down until you find 'Settings'"
- "Get all clickable elements and their positions"
- "Type 'test@email.com' into the current field"

### Debugging
- "Show me the last 50 Flutter logs"
- "Are there any crash logs for my app?"
- "What's the memory usage of com.myapp?"

### Visual QA
- "Capture this screen for comparison with Figma"
- "Take a screenshot and tell me about the UI structure"
- "Set the font scale to 1.3 and take a screenshot for accessibility testing"

### Performance Testing
- "Set animation scale to 0 and run through the app"
- "Get frame stats for my app - is there any jank?"
- "What's the GPU rendering performance?"

### Device Simulation
- "Change the screen to 1080x1920 to simulate a smaller phone"
- "Rotate to landscape mode"
- "Set location to San Francisco (37.7749, -122.4194)"

## Extending

Add new tools easily:

```python
@mcp.tool()
def my_custom_tool(param: str, device_serial: str | None = None) -> str:
    """Description shown to AI"""
    return run_adb(["shell", "your-command", param], device_serial)
```

## Tips for Flutter Development

1. **Speed up tests**: Use `set_animation_scale(0)` to disable animations
2. **Visual QA**: Use `capture_screen_for_comparison()` with Figma MCP
3. **Debug logs**: `get_flutter_logs()` filters Flutter-specific output
4. **Hot reload**: Keep `flutter run` terminal open, use device for interaction
5. **Responsive testing**: Use `change_screen_size()` and `change_density()`

## License

MIT