martingeidobler/android-mcp-server

MCP server for controlling Android emulators and devices via ADB. Gives AI assistants the ability to see, interact with, and debug Android apps — taking screenshots, tapping elements, reading logs, and documenting bugs.
npm Package | GitHub | Issues
^ Sped up for better viewing. More demos and test cases.
Features
- **25 tools** for complete Android device control
- **Screenshot capture** with intelligent compression (Sharp-based, max 1280px)
- **UI tree inspection** — read element hierarchy with bounds, text, resource IDs, and state
- **Touch automation** — tap, swipe, scroll, type text, press hardware keys
- **Element targeting** — find and tap elements by resource-id, text, or content-desc
- **App lifecycle** — install APKs, launch apps, inspect current activity
- **Logcat integration** — filter by package, log level, or timestamp
- **Device management** — list devices, start emulators, get device info
- **Compound actions** — tap_and_wait combines tap + settle + UI tree in one round trip
- **Persistent ADB shell** — reuses a single shell session for faster command execution
- **Device info caching** — queries device properties once per session
- **Multi-device support** — target specific devices by ID
- **Zero app modifications** — works with any Android app via ADB, no SDK integration needed
Prerequisites
- Node.js 18+
- Android SDK with platform-tools (ADB) and emulator
- A running Android emulator or connected device
Finding your ANDROID_HOME
The server auto-discovers the SDK at ~/Library/Android/sdk (macOS) or via ANDROID_HOME. If your SDK is elsewhere, set ANDROID_HOME in the MCP config (see below).
To check:
Setup
Claude Code
This registers the server globally so it's available in all projects. Use --scope project instead to limit it to the current project.
If your SDK is not in the default location:
Claude Desktop
Add to your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
VS Code
Add to your VS Code settings (.vscode/settings.json):
Cursor
Add to your Cursor MCP config (~/.cursor/mcp.json):
Windsurf
Add to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):
Project config (.mcp.json)
Add to your project's .mcp.json (checked into version control so your team gets it too):
Build from source
Available Tools
Device Management
| Tool | Description |
|------|-------------|
| list_devices | List connected Android devices and emulators |
| list_avds | List available Android Virtual Devices |
| start_emulator | Start an AVD by name (waits up to 60s) |
Screenshot & UI Analysis
| Tool | Description |
|------|-------------|
| screenshot | Take screenshot for visual analysis. Optional save_path to save to disk |
| get_ui_tree | Get UI element hierarchy with bounds, text, resource IDs, and state |
Interaction
| Tool | Description |
|------|-------------|
| tap | Tap at screen coordinates |
| tap_element | Tap element by resource-id, text, or content-desc |
| tap_and_wait | Tap element, wait for UI to settle, return new UI tree — single round trip |
| long_press | Long press at coordinates (context menus, drag handles) |
| double_tap | Double tap at coordinates |