Android Automation with goandroid
Automate Android devices using the goandroid library - a pure Go implementation that uses ADB (Android Debug Bridge) to interact with Android devices without requiring Java backends, UI Automator wrappers, or installing APKs on devices.
What This Skill Does
This skill helps you work with the goandroid Android automation library, which provides:
Touch, swipe, and gesture input automationUI element discovery and interaction via XML hierarchy dumpsActivity lifecycle management (launch apps, wait for focus)Device property inspection and file managementDisplay and geometry utilities for coordinate calculationsComprehensive MCP server with 134 tools across 27 handler categoriesPrerequisites
Android Debug Bridge (ADB) must be installed and available in system PATHAndroid device connected via USB or network with USB debugging enabledGo 1.24.4 or laterRoot access on device required for some operations (handled automatically)Instructions
1. Understanding the Architecture
The library follows a modular architecture:
**Core Components:**
`AndroidManager` - Factory for creating device instances with configurable ADB timeout`Android` - Main device interface aggregating all subsystems`Device` - Low-level ADB communication (`device/device.go`)`Input` - Touch, key, text input (`input/`)`View` - UI element discovery via uiautomator XML dumps (`view/view.go`)`Activity` - Activity lifecycle management (`activity/activity.go`)`Display` - Screen properties (`display/display.go`)`Geometry` - Coordinate utilities (`geometry/geometry.go`)`AdbUtility` - Core ADB command execution (`adbutility/adbutility.go`)**MCP Server:**
Dual transport: stdio and HTTP modes134 tools organized into 27 handler filesCategories: device management, input operations, view operations, activity/display/geometry2. Building and Running
**Build the library:**
```bash
go build ./...
go mod tidy
```
**Build MCP server:**
```bash
cd cmd/mcp-server && go build -o goandroid-mcp-server .
```
**Run MCP server (stdio mode):**
```bash
cd cmd/mcp-server && go run . --adb-path="adb" --timeout=60
```
**Run MCP server (HTTP mode):**
```bash
cd cmd/mcp-server && go run . --adb-path="adb" --timeout=60 --http=":8080"
```
3. Writing Automation Code
**Basic usage pattern:**
1. Create AndroidManager with timeout and ADB path
2. Get Android device instance by serial number
3. Use subsystem interfaces for automation
4. Handle errors properly
**Example structure:**
```go
// Create manager
manager := goandroid.NewAndroidManager(60, "adb")
// Get device
device, err := manager.GetAndroid("DEVICE_SERIAL")
if err != nil {
// handle error
}
// Use subsystems
device.Input.Tap(x, y)
device.View.FindByText("Button")
device.Activity.LaunchApp("com.example.app")
```
4. Working with UI Elements
UI interaction uses XML hierarchy dumps from `uiautomator dump`:
`View` struct represents UI elements with calculated center pointsFind elements by text, resource ID, class, content descriptionClick, scroll, check presence of elementsSupport for cross-reference matching (AND/OR conditions)5. Input Operations
**Available input types:**
Touchscreen: taps, swipes, gesturesKey events: press hardware/system keysText input: type text into focused fieldsAdvanced: multi-touch, long press, shortcuts6. MCP Server Development
**Handler pattern:**
Handlers organized by functionality in `mcp/handlers/`Registry system in `mcp/registry/registry.go`Tool registration via `mcpServer.AddTool()` patternDevice validation: `if device == (goandroid.Android{}) {}`**Import cycle resolution:**
Use `mcp/common/helpers.go` for shared utilitiesFollow consistent error handling and JSON marshaling7. Testing and Debugging
```bash
go test ./... # Run tests
go run example.go # Run example code
go doc ./... # Generate documentation
gofmt -w . # Format code
```
8. Key Implementation Notes
All operations are ADB-basedDevice interactions use XML dumpsRoot access handled automatically when neededUses only Go standard library + internal packagesModule path: `github.com/kunaldawn/goandroid`Common Tasks
**List connected devices:**
Use ADB utility subsystem to enumerate devices
**Launch an app:**
Use Activity subsystem with package name
**Find and click a button:**
Use View subsystem to find by text, then Input subsystem to tap coordinates
**Take a screenshot:**
Use Device subsystem file operations
**Get screen dimensions:**
Use Display subsystem
**Swipe or gesture:**
Use Input subsystem swipe/gesture methods
Constraints
Requires ADB executable in PATHDevice must have USB debugging enabledSome operations require root accessUI element discovery depends on accessibility information being availableXML parsing performance depends on UI complexityFile Locations
Core library: root package and subpackages (`activity/`, `input/`, `view/`, etc.)MCP server: `cmd/mcp-server/`, `mcp/server.go`Handler registry: `mcp/registry/registry.go`Handler implementations: `mcp/handlers/`Module definition: `go.mod` (Go 1.24.4)