README.md
Android MCP Server
This is a Model Context Protocol (MCP) server that enables control of Android devices using uiautomator2.
Prerequisites
- Python 3.10+
- ADB installed and added to PATH
- An Android device connected via USB or WiFi (with ADB debugging enabled)
Installation
- Create a virtual environment:
python -m venv venv .\venv\Scripts\activate - Install dependencies:
pip install -r requirements.txt
Usage
To run the server:
python main.py
Tools Available
connect_device(serial): Connect to a device.device_info(): Get device status.dump_hierarchy(): View UI XML.click_element(text, resource_id, description): Click UI elements.wait_for_element(text, resource_id, description, timeout): Wait for element to appear.click_point(x, y): Click at coordinates.swipe(sx, sy, ex, ey): Swipe gesture.input_text(text, clear): Type text.press_key(key): Press physical keys (home, back, etc.).open_app(package_name): Launch an app.stop_app(package_name): Stop an app.install_app(url_or_path): Install APK.uninstall_app(package_name): Uninstall app.shell_command(command): Run ADB shell command.take_screenshot(): Capture screen.
Configuration
Ensure your device is visible via adb devices before connecting.
Gemini MCP Configuration
To use this server with Gemini CLI or compatible MCP clients, add the following to your MCP configuration file (e.g., ~/.gemini/settings.json):
"android": {
"command": "d:\\src\\android-mcp\\venv\\Scripts\\python.exe",
"args": [
"d:\\src\\android-mcp\\main.py"
]
}
Replace the paths with the actual absolute paths to your project if they differ.
Tools 15
connect_deviceConnect to a specific Android device using its serial number.device_infoRetrieve the current status and information of the connected device.dump_hierarchyCapture and view the current UI XML hierarchy of the device screen.click_elementPerform a click action on a UI element identified by text, resource ID, or description.wait_for_elementWait for a specific UI element to appear on the screen within a timeout period.click_pointPerform a click action at specific X and Y coordinates.swipePerform a swipe gesture from start coordinates to end coordinates.input_textType text into the active input field, with an option to clear it first.press_keySimulate pressing physical device keys like home, back, or volume.open_appLaunch an application using its package name.stop_appForce stop an application using its package name.install_appInstall an APK file from a provided URL or local path.uninstall_appUninstall an application using its package name.shell_commandExecute a raw ADB shell command on the device.take_screenshotCapture a screenshot of the current device screen.Try it
→Connect to my Android device and tell me its current status.
→Open the Settings app on my phone and take a screenshot.
→Find the login button on the screen and click it.
→Install the APK located at /path/to/app.apk and then launch it.
→Swipe up on the screen to refresh the feed.