Android MCP

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

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

Usage

Development Commands

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:

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

Claude CLI Setup

Manual Setup:

Usage Examples:

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:

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.