Android MCP Server

A Model Context Protocol (MCP) server that provides powerful inspection and interaction tools for connected android devices or emulators.

Features

• Device Management: List and manage connected Android devices via ADB with automatic fallback paths
• Enhanced UI Hierarchy Inspection: Extract complete UI hierarchy using Layout Inspector features with enhanced attributes
• Debug View Attributes: Access detailed view attributes and layout parameters
• Element Search: Find UI elements by resource ID, text content, or class name with exact matching options
• User Interaction: Click, swipe, and input text on Android devices with coordinate precision
• Activity Information: Get current foreground activity details with window state information
• Performance Optimized: Uses coroutines and caching for improved response times

Requirements

• Java 17+ (required for Kotlin)
• Android SDK Platform Tools (for ADB) - automatically detects from:
  • System PATH
  • ~/Library/Android/sdk/platform-tools/adb (macOS)
  • ~/Android/Sdk/platform-tools/adb (Windows/Linux)
  • /usr/local/bin/adb (Homebrew)
  • /opt/android-sdk/platform-tools/adb (Linux)
• Connected Android device (physical device or emulator)
• Developer options and USB debugging enabled on the Android device

Installation & Setup

Option 1: Download from GitHub Releases (Recommended)

1. Download the latest release from GitHub Releases
2. Download android-mcp.jar from the latest release
3. Verify integrity (optional but recommended):

   sha256sum android-mcp.jar
   # Compare with the .sha256 file from the release
   

Option 2: Build from Source

# Clone the repository
git clone https://github.com/ulcica/android-mcp.git
cd android-mcp

# Build the Kotlin JAR file
./gradlew build

Configure Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "android-mcp": {
      "command": "java",
      "args": ["-jar", "/path/to/android-mcp/build/libs/android-mcp.jar"]
    }
  }
}

Usage

Development Commands

# Build and run the Kotlin server
./gradlew run

# Build only
./gradlew build

# Run tests
./gradlew test

# Run the JAR directly
java -jar build/libs/android-mcp.jar

# Check version
java -jar build/libs/android-mcp.jar --version

# Show help
java -jar build/libs/android-mcp.jar --help

Available Tools

The Kotlin MCP server provides 11 comprehensive tools:

1. get_device_list

Lists all connected Android devices.

Input: None Output: Array of connected devices with their IDs, states, and models

2. get_app_list

Gets list of installed applications on the Android device.

Input:

• deviceId (optional): Android device ID
• includeSystemApps (optional): Include system applications in the list (default: false, shows only user-installed apps)

Output: Array of installed applications with package names, sorted alphabetically

3. get_current_activity

Gets enhanced information about the current foreground activity.

Input:

• deviceId (optional): Android device ID

Output: Current package name, activity name, PID, and window state information

3. get_view_attributes

Gets UI hierarchy with enhanced view attributes by temporarily enabling debug mode.

Input:

• deviceId (optional): Android device ID

Output: UI hierarchy with detailed view attributes, layout parameters, and debug information

4. find_elements

Searches for UI elements using various criteria.

Input:

• deviceId (optional): Android device ID
• resourceId (optional): Resource ID to search for
• text (optional): Text content to search for
• className (optional): Class name to search for
• exactMatch (optional): Whether to use exact text matching (default: false)

Output: Array of matching UI elements

5. view_hierarchy

Gets the UI view hierarchy from uiautomator dump with rotation information.

Input:

• deviceId (optional): Android device ID

Output: Structured view hierarchy with device info, timestamp, rotation, and UI element tree

6. click_coordinate

Clicks at specific (x,y) coordinates on the Android device screen.

Input:

• x (required): X coordinate to click
• y (required): Y coordinate to click
• deviceId (optional): Android device ID

Output: Success confirmation with device info, coordinates, and timestamp

7. swipe_coordinate

Swipe from start (x,y) coordinates to end (x,y) coordinates on the Android device screen.

Input:

• deviceId (optional): Android device ID
• 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)

Output: Success confirmation with device info, coordinates, duration, and timestamp

8. input_text

Input text on the Android device (types text into focused field).

Input:

• deviceId (optional): Android device ID
• text (required): Text to input on the device

Output: Success confirmation with device info, text, and timestamp

9. key_event

Send key event to Android device (e.g., Enter=66, Back=4, Home=3).

Input:

• deviceId (optional): Android device ID
• keyCode (required): Android key code (e.g., 66 for Enter, 4 for Back)

Output: Success confirmation with device info, key code, and timestamp

10. start_intent

Start an Android intent/activity with specified parameters (launch apps, open URLs, etc.).

Input:

• deviceId (optional): Android device ID
• action (optional): Intent action (e.g., 'android.intent.action.MAIN', 'android.settings.SETTINGS')
• category (optional): Intent category (e.g., 'android.intent.category.LAUNCHER')
• dataUri (optional): Data URI for the intent (e.g., 'https://example.com', 'tel:+1234567890')
• packageName (optional): Target package name (e.g., 'com.android.settings')
• className (optional): Target class name (e.g., 'com.android.settings.Settings')
• extras (optional): String extras to pass with the intent as key-value pairs

Output: Success confirmation with device info, intent parameters, and timestamp

Architecture

Kotlin-Specific Improvements

• Coroutines: All ADB operations use Kotlin coroutines for non-blocking execution
• Type Safety: Leverages Kotlin's null safety and type system
• Data Classes: Clean, immutable data structures with built-in serialization
• Sealed Classes: Type-safe error handling with sealed error classes
• Concurrency: Better thread safety with concurrent data structures
• Clean Architecture: SOLID principles with separated concerns and focused classes
• Parameter Optimization: SwipeParams data class reduces parameter count from 7+ to 2
• Specific Exception Handling: Enhanced error types for better debugging and handling

Key Components

Main (Main.kt)

• Entry point that starts the MCP server using coroutines

MCP Server (McpServer.kt)

• Handles JSON-RPC communication over stdio
• Implements all MCP tool endpoints
• Manages device caching and connection pooling

ADB Manager (AdbManager.kt)

• Refactored facade coordinating specialized components following SOLID principles
• Delegates to focused classes: DeviceManager, UIInspector, DeviceInputController
• Maintains backward compatibility while providing cleaner architecture
• Provides both legacy parameter methods and new SwipeParams-based methods

Specialized ADB Components:

• AdbPathResolver: Auto-discovery of ADB path with caching and fallback strategies
• DeviceManager: Device listing and management operations with connection pooling
• UIInspector: UI hierarchy inspection with debug mode and XML extraction
• DeviceInputController: All input operations (tap, swipe, text, key events)
• ShellCommandExecutor: Persistent ADB shell connections with command batching

UI Hierarchy Parser (UIHierarchyParser.kt)

• Custom XML parser for Android UI hierarchies
• Element search utilities with functional programming patterns
• Support for enhanced Layout Inspector attributes
• XmlExtractionUtils: Dedicated utility for XML content extraction with multiple fallback strategies

Type System (model/ package)

• Comprehensive Kotlin data classes with serialization support
• Enhanced sealed class hierarchy for type-safe error handling
• SwipeParams data class for parameter optimization
• AndroidMcpConstants for centralized configuration
• Enum classes for device states and comprehensive error codes

Performance Optimizations

The Kotlin version includes several performance improvements:

1. Coroutine-based Execution: Non-blocking ADB operations
2. Advanced Caching: Device list and ADB path caching with TTL
3. Connection Pooling: Persistent device connections with cleanup
4. Parallel Processing: Concurrent execution of independent ADB commands
5. Reduced Latency: Optimized debug mode timing (200ms vs 500ms)

UI Element Properties

Each UI element in the hierarchy contains the following properties:

• class: Android class name (e.g., "android.widget.TextView")
• package: App package name
• text: Visible text content (if any)
• resource-id: Android resource identifier
• content-desc: Content description for accessibility
• bounds: Element bounds {left, top, right, bottom}
• Boolean properties: checkable, checked, clickable, enabled, focusable, focused, scrollable, long-clickable, password, selected, visible
• children: Array of child UI elements

Error Handling

The Kotlin version uses sealed classes for type-safe error handling with enhanced specific exception types:

sealed class LayoutInspectorError {
    class AdbNotFound(message: String)
    class DeviceNotFound(message: String, deviceId: String?)
    class UiDumpFailed(message: String, deviceId: String?)
    class ParseError(message: String, deviceId: String?)
    class ConnectionClosed(message: String, deviceId: String?)
    class CommandTimeout(message: String, deviceId: String?)
    class ShellCommandFailed(message: String, deviceId: String?)
    class McpProtocolError(message: String, deviceId: String?)
    class UnknownError(message: String, deviceId: String?)
}

The server includes comprehensive error handling with specific error codes:

• ADB_NOT_FOUND: ADB command not found in PATH
• DEVICE_NOT_FOUND: Specified Android device not found
• UI_DUMP_FAILED: Failed to dump UI hierarchy
• PARSE_ERROR: Failed to parse XML hierarchy
• CONNECTION_CLOSED: ADB connection closed unexpectedly
• COMMAND_TIMEOUT: Command execution timeout
• SHELL_COMMAND_FAILED: Shell command execution failed
• MCP_PROTOCOL_ERROR: MCP protocol violations
• UNKNOWN_ERROR: Generic error

Development

See Development.md for detailed development information including:

• Project structure and architecture
• Building from source
• Version management
• Testing procedures
• Code quality guidelines
• Release process
• Contributing guidelines

MCP Integration

This server implements the Model Context Protocol and can be used with any MCP-compatible client:

1. Claude Desktop: Add to your MCP configuration
2. Claude CLI: Add to your CLI configuration
3. Custom Applications: Connect via stdio transport
4. Development Tools: Use for Android app testing and analysis

Claude Desktop Configuration

{
  "mcpServers": {
    "android-mcp": {
      "command": "java",
      "args": ["-jar", "/path/to/android-mcp/build/libs/android-mcp.jar"]
    }
  }
}

Claude CLI Setup

Manual Setup:

claude mcp add android-mcp java -jar /path/to/android-mcp/build/libs/android-mcp.jar

Usage Examples:

claude "List my connected Android devices"
claude "Show me the installed apps on my Android device"
claude "Get all apps including system apps from my Android device"
claude "Show me the UI hierarchy of my Android screen"
claude "Get the view hierarchy with rotation info from my Android device"
claude "Find elements with text Settings on my Android device"
claude "Click at coordinates 200,300 on my Android device"
claude "Swipe from 100,500 to 100,200 on my Android device"
claude "Input text 'hello world' on my Android device"
claude "Send Enter key (code 66) to my Android device"
claude "Start intent with action android.intent.action.MAIN and category android.intent.category.LAUNCHER"
claude "Open Settings app using start intent"

Use Cases

• UI Testing: Automated testing of Android applications
• App Discovery: Discover and analyze installed applications on Android devices
• Accessibility Analysis: Analyze app accessibility properties
• Layout Debugging: Debug layout issues and element positioning
• App Analysis: Reverse engineer app UI structures and discover available packages
• Quality Assurance: Validate UI consistency across screens
• Automated Interaction: Programmatically interact with Android apps through touch events, swipes, and text input
• Performance Testing: Measure UI response times and interaction latencies
• User Journey Automation: Automate complex user workflows and scenarios

Troubleshooting

Common Issues

1. Java Version: Ensure Java 17+ is installed
2. ADB Path: Make sure Android SDK platform-tools are in PATH
3. Device Connection: Verify device is connected and authorized
4. JAR Location: Update paths in Claude config if JAR location changes

ADB Issues

• The server automatically searches for ADB in common locations
• If ADB is not found, install Android SDK platform-tools
• Verify USB debugging is enabled on your Android device
• Check device authorization status with adb devices (or use full path if needed)

Permission Issues

• Ensure your Android device is authorized for debugging
• Check that the connected device appears in adb devices

UI Dump Failures

• Some apps may block UI inspection for security reasons
• Ensure the target app is in the foreground
• Try refreshing the device connection

Debug Mode

Add logging to see detailed ADB command execution:

// In AdbManager.kt, uncomment debug statements
System.err.println("Executing: ${command.joinToString(" ")}")

Releases

This project uses automated GitHub releases. New versions are automatically built and published when tags are created.

Release Process

1. Update version in build.gradle.kts
2. Commit changes and create a git tag:

   git tag v1.2.0
   git push origin v1.2.0
   

3. GitHub Actions automatically:
   • Builds the JAR file
   • Runs tests on Java 17 and 21
   • Creates a GitHub release
   • Uploads android-mcp.jar with checksums
   • Generates changelog from commit messages

Download Latest Release

Always download the latest version from GitHub Releases for the most stable experience.

License

MIT License.