Android-Mobile

Android Mobile MCP bridges the Model Context Protocol with Android device automation, enabling AI agents to interact with Android devices through UI manipulation, app management, and screen capture. This server exposes a suite of tools that let you inspect the current UI, simulate touches and gestures, enter text, press system keys, and manage apps on a connected Android device. By leveraging these capabilities, an agent can discover UI structure, perform precise interactions, navigate apps, and capture screen content for analysis.

To use the tools, start the MCP server with the configured command and then invoke the provided tool endpoints. Tools like mobile_dump_ui and mobile_take_screenshot provide state inspection and visual context, while mobile_click, mobile_swipe, and mobile_type enable user-like interactions. Use mobile_key_press for navigation and system actions, and mobile_list_apps and mobile_launch_app to query and run applications on the device. Ensure you have a properly connected device and that ADB is accessible from your environment before issuing tool commands.

Prerequisites

• A physical Android device or emulator with USB/access enabled and ADB installed
• USB debugging enabled on the Android device
• A machine with the MCP runtime environment and the uvx tool available

Installation steps

1. Install the uvx runner (or ensure it is available in your PATH)

   • Example (adjust to your environment): curl -sS https://example.com/install-uvx.sh | bash
   • Verify installation: uvx --version

2. Prepare the Android-Mobile-MCP package

   • The MCP server is provided as the android-mobile-mcp package. Ensure your environment can resolve and fetch this package via uvx.

3. Run the MCP server using the configuration provided in this README

   • The server is invoked via the mcp_config shown in this document. You can start it by selecting the configured command and argument: uvx android-mobile-mcp

4. Verify device connection

   • Ensure adb devices lists your device: adb devices
   • If prompted, authorize the computer on the Android device.

5. Optional: configure environment variables for adb path or device targets if needed by your setup.

   • Example: export ADB_PATH=/path/to/adb

6. Test a tool

   • After the server starts, test a simple tool like mobile_dump_ui to confirm UI parsing works: uvx android-mobile-mcp --tool mobile_dump_ui

Tips and common issues:

• Ensure the Android device remains connected and USB debugging stays enabled during sessions; unstable connections can cause UI element detection to fail.
• The mobile_dump_ui tool returns a hierarchical JSON of UI elements and their coordinates; ensure you call it before attempting interactions at calculated coordinates.
• Coordinate-based actions (mobile_click, mobile_swipe) require a recent UI dump to validate element positions; stale dumps can lead to invalid actions.
• For screen capture (mobile_take_screenshot), large PNG data may be returned; ensure your environment can handle binary payloads if integrating programmatically.
• If you encounter permission or ADB authorization prompts, manually approve the prompt on the device during first use.
• When launching apps (mobile_launch_app), the tool validates package existence; ensure the target app is installed and launchable on the device.
• If you need to automate frequent app launches or workflows, consider scripting sequences of mobile_dump_ui, mobile_click, mobile_type, and mobile_key_press to simulate complete user tasks.