CursorTouch/Android-MCP: LLM-Controlled Android Automation Without CV Pipelines
Android automation has long been trapped between two imperfect worlds: brittle preprogrammed scripts that break on every UI update, and computer-vision pipelines that demand expensive model fine-tuning and substantial compute overhead. For developers building AI agents that need to interact with real mobile applications, neither approach scales cleanly. CursorTouch/Android-MCP enters this gap as a lightweight, open-source bridge—running as a Model Context Protocol (MCP) server that lets any LLM or VLM control Android 10+ devices through native ADB and accessibility APIs, no custom vision models required.
What is CursorTouch/Android-MCP?
CursorTouch/Android-MCP is an MIT-licensed Python↗ Bright Coding Blog 3.13 project maintained by CursorTouch (developers Jeomon George and Muhammad Yaseen) that implements the Model Context Protocol for Android device interaction. With 736 GitHub stars and 102 forks as of its last commit on July 1, 2026, it occupies a specific but growing niche: enabling LLM agents to perform concrete mobile tasks—app navigation, UI element interaction, text input, gesture execution, and shell command invocation—through a standardized tool-calling interface rather than ad-hoc integrations.
The project's architectural bet is clear and documented: instead of requiring developers to train or deploy specialized computer-vision models for screen understanding, it leverages Android's built-in Accessibility API and ADB's view hierarchy capabilities to expose structured UI state to the LLM. This design choice matters because it decouples the automation layer from the model layer. You can swap GPT-4 for Claude, local Llama, or any future VLM without retraining a companion vision system. The server handles device communication; your chosen LLM handles reasoning and planning.
This approach also sidesteps the latency and cost penalties of screenshot-only automation. While CursorTouch/Android-MCP does support screenshot capture (with optional quantization to reduce token consumption), its primary interaction mode uses structured accessibility data—element bounds, text labels, clickable states—yielding the documented 2-4 second typical latency between sequential actions.
Key Features
Native Android Integration via ADB and Accessibility API
The server communicates with devices through standard Android Debug Bridge (ADB) commands and the Android Accessibility API. This enables precise operations: launching applications by package name, tapping specific screen coordinates, executing swipe and drag gestures, injecting text input, and reading complete view hierarchies. These are not simulated touch events at the OS level but instrumented interactions that respect Android's security model and accessibility framework.
Bring Your Own LLM/VLM
CursorTouch/Android-MCP imposes no model vendor lock-in. The MCP protocol standardizes tool definitions, so any compatible client—Claude Desktop, OpenCode, or custom implementations—can invoke its tools. The README explicitly notes: "Works with any language model, no fine-tuned CV model or OCR pipeline required." This matters for teams with data residency requirements, cost constraints, or preference for open-weight models.
Rich Pre-Built Toolset
The server exposes eleven documented tools through the MCP interface: State-Tool (device and UI state snapshot), Click-Tool, Long-Click-Tool, Type-Tool (with optional text clearing), Swipe-Tool, Drag-Tool, Press-Tool (hardware key simulation including Back and Volume controls), Wait-Tool, Notification-Tool, Shell-Tool (arbitrary command execution), and a second State-Tool variant combining active app detection with interactive element enumeration. This coverage handles most mobile automation scenarios without custom extension.
Lazy Device Resolution
A pragmatic design decision: the server starts independently of device availability and resolves connections only when tools are invoked. If no device is configured, it auto-detects from adb devices, preferring physical hardware over emulators. This prevents MCP handshake failures during client startup and supports dynamic device attachment in CI or shared development environments.
Flexible Connectivity
USB serial targeting, WiFi ADB (auto-appending port 5555), environment-variable configuration, and explicit command-line flags all coexist. The README documents six distinct device selection patterns plus three environment variables, accommodating everything from single-device development to multi-device test farms.
Use Cases
Automated QA and Regression Testing
Mobile QA teams can encode test procedures as natural language prompts executed through their LLM of choice, with CursorTouch/Android-MCP translating intent into concrete ADB actions. The structured accessibility data provides more reliable element targeting than coordinate-based tapping, reducing breakage from minor UI adjustments. The Shell-Tool enables verification of backend state, log extraction, or database inspection mid-test.
Accessibility Research and Assistive Technology Prototyping
Developers building assistive agents can leverage the Notification-Tool and State-Tool to construct real-time awareness of device context, then drive interactions through the same pipeline. The Accessibility API foundation means the toolset already operates within Android's accessibility permission model—a legal and technical requirement for production assistive apps.
LLM Agent Benchmarking on Mobile Tasks
Researchers evaluating multimodal model capabilities on real-world mobile operation benefit from a standardized, reproducible environment. CursorTouch/Android-MCP's deterministic tool definitions and state reporting enable consistent evaluation across model versions or competing architectures, with the 2-4s action latency providing a realistic operational tempo.
Rapid UI Prototyping and Demo Automation
Product teams can script repeatable demo flows across devices without maintaining fragile macro recordings. The Wait-Tool accommodates variable network conditions; the Press-Tool handles system interruptions like volume changes or back navigation that would derail pure coordinate scripts.
DevOps↗ Bright Coding Blog and Device Farm Integration
The lazy connection model and environment-variable configuration suit containerized deployment. A test orchestrator can spin up CursorTouch/Android-MCP instances pointing at specific devices in a farm, with the MCP protocol providing clean separation between test logic and device control.
Installation & Setup
Prerequisites
Before installation, verify you have:
- Python 3.13 (the project targets this version specifically)
- ADB installed and available in your PATH
- An Android 10+ device or emulator with USB debugging enabled
Verify ADB Connectivity
Connect your device via USB or start your emulator, then:
adb devices
Expected output:
List of devices attached
R38M30XXXXX device
Serial numbers vary by device; emulators typically show emulator-5554. An empty list or "unauthorized" status indicates USB debugging is not enabled on the device. For WiFi ADB:
adb connect 192.168.1.3:5555
adb devices
Option 1: UVX (Recommended for Claude Desktop)
UVX eliminates manual dependency management. The README notes a Windows-specific constraint: Python 3.14 fails to resolve a transitive pywin32 dependency, so the --python 3.13 flag is mandatory there.
Locate your Claude Desktop configuration:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Add this configuration:
{
"mcpServers": {
"android-mcp": {
"command": "uvx",
"args": [
"--python",
"3.13",
"android-mcp"
]
}
}
}
The server starts immediately but connects lazily when tools run. Without explicit device configuration, it auto-detects and prefers physical devices over emulators.
For a specific WiFi device via environment variables:
{
"mcpServers": {
"android-mcp": {
"command": "uvx",
"args": [
"--python",
"3.13",
"android-mcp"
],
"env": {
"ANDROID_MCP_CONNECTION": "wifi",
"ANDROID_MCP_HOST": "192.168.1.3"
}
}
}
}
Or pass flags directly:
{
"mcpServers": {
"android-mcp": {
"command": "uvx",
"args": [
"--python",
"3.13",
"android-mcp",
"--wifi",
"192.168.1.3"
]
}
}
}
Option 2: UV Mode (Local Development)
Clone and install dependencies:
git clone https://github.com/CursorTouch/Android-MCP.git
cd Android-MCP
uv sync
The uv sync command respects the repository's .python-version file, defaulting to Python 3.13. Then configure Claude Desktop:
{
"mcpServers": {
"android-mcp": {
"command": "uv",
"args": [
"--directory",
"</PATH/TO/Android-MCP>",
"run",
"android-mcp"
]
}
}
}
Replace </PATH/TO/Android-MCP> with your actual cloned path. Append "--device", "<SERIAL>", "--wifi", "192.168.1.3", or "--usb" to the args array for explicit device control.
Option 3: OpenCode Integration
After cloning and uv sync, add to your opencode.json:
{
"mcp": {
"android-mcp": {
"type": "local",
"command": ["uv", "--directory", "</PATH/TO/Android-MCP>", "run", "android-mcp"]
}
}
}
As with UV mode, append device selection flags to the command array as needed.
Final Step
Restart Claude Desktop. "android-mcp" should appear in available integrations. For log locations and common ADB issues, the README references MCP documentation.
Real Code Examples
The README contains configuration examples rather than executable Python scripts, reflecting CursorTouch/Android-MCP's nature as an MCP server invoked by client configuration. Below are the documented patterns with operational context.
Example 1: Basic UVX Configuration with Auto-Detection
{
"mcpServers": {
"android-mcp": {
"command": "uvx",
"args": [
"--python",
"3.13",
"android-mcp"
]
}
}
}
This is the minimal viable configuration. The --python 3.13 constraint prevents the pywin32 resolution failure on Windows. The absence of device arguments triggers auto-detection from adb devices, with physical devices preferred over emulators. This suits single-device development workflows where the target changes infrequently.
Example 2: Explicit WiFi Device with Environment Variables
{
"mcpServers": {
"android-mcp": {
"command": "uvx",
"args": [
"--python",
"3.13",
"android-mcp"
],
"env": {
"ANDROID_MCP_CONNECTION": "wifi",
"ANDROID_MCP_HOST": "192.168.1.3"
}
}
}
}
Environment variables separate connection parameters from command structure, which simplifies rotating between test devices without JSON syntax changes. The ANDROID_MCP_HOST value receives automatic :5555 port suffixing when omitted. This pattern suits device farms or CI environments where host addresses are injected from secrets management.
Example 3: Local Development with UV and Explicit USB Device
git clone https://github.com/CursorTouch/Android-MCP.git
cd Android-MCP
uv sync
{
"mcpServers": {
"android-mcp": {
"command": "uv",
"args": [
"--directory",
"/home/dev/projects/Android-MCP",
"run",
"android-mcp",
"--device",
"RFCN2013V8D"
]
}
}
}
The --directory flag anchors UV to the cloned repository; --device locks to a specific USB serial. This eliminates ambiguity when multiple devices are connected and ensures consistent targeting across server restarts. The uv sync step is critical—it resolves dependencies through the project's lockfile, preventing version drift.
The README does not contain additional executable code examples beyond these configuration patterns. Developers seeking programmatic interaction would implement MCP clients in their language of choice, invoking the documented tools through the protocol. [INTERNAL_LINK: MCP protocol implementation guides]
Advanced Usage & Best Practices
Token Optimization for Vision-Heavy Workflows
Set SCREENSHOT_QUANTIZED=true when your LLM client uses screenshot analysis. The README documents this as a token reduction mechanism, though specific compression ratios are not quantified. For pure accessibility-tree workflows (State-Tool without visual analysis), leave this unset to avoid unnecessary image processing overhead.
Device Selection in Multi-Device Environments
The auto-detection heuristic (physical over emulator) may not suit all workflows. Explicit --device or ANDROID_MCP_DEVICE configuration prevents misidentification when both test hardware and emulators are present. For CI pipelines, prefer environment variables over command-line flags—they're easier to rotate without configuration file commits.
Security Boundaries
The README's caution bears emphasis: "Android-MCP can execute arbitrary UI actions on your mobile device." The Shell-Tool specifically enables unrestricted command execution. Restrict to emulators or dedicated test devices when evaluating untrusted agent prompts. The accessibility service permission model provides some Android-level containment, but this is not a sandboxed execution environment.
Latency Expectations
Documented 2-4 second inter-action latency reflects real-world ADB round-trips and accessibility API queries, not network overhead. Design agent prompts to batch independent operations rather than assuming sub-second responsiveness. The Wait-Tool exists for explicit synchronization; use it after state-changing operations that trigger animations or network requests.
Connection Resilience
The lazy connection model means transient ADB disconnections during server idle periods don't crash the MCP client. However, mid-operation disconnections will surface as tool errors. For WiFi ADB, monitor connection stability—Android's WiFi debugging can drop during device sleep or network transitions.
Comparison with Alternatives
| Tool | Approach | Model Coupling | Key Trade-off |
|---|---|---|---|
| CursorTouch/Android-MCP | MCP server, ADB + Accessibility API | None (BYO LLM) | Requires Android 10+, MCP client support |
| Appium | WebDriver protocol, UIAutomator/Espresso | None | Heavier infrastructure, no native LLM tool interface |
| Maestro | YAML flows, screenshot-based | None | Simpler for scripted flows, less flexible for dynamic agent reasoning |
| scrcpy + custom scripts | ADB screen mirroring, manual automation | User-implemented | Minimal abstraction, full implementation burden on developer |
Appium remains the established choice for cross-platform mobile testing with extensive language bindings, but its WebDriver heritage doesn't integrate cleanly with modern LLM tool-calling patterns. Maestro excels at reliable, repeatable flow execution but constrains you to predeclared YAML structures rather than dynamic agent reasoning. CursorTouch/Android-MCP's specific advantage is protocol-level integration with MCP-compatible agents—if your stack already uses Claude Desktop or OpenCode, the activation energy is lower than bridging Appium through additional abstraction layers.
FAQ
What Android versions are supported? Android 10 and above. The Accessibility API surface used by the toolset stabilized in this release.
Can I use this with local LLMs? Yes. Any MCP-compatible client can invoke the server; model hosting is entirely external.
Why Python 3.13 specifically?
The project targets 3.13 and uses .python-version for dependency resolution. Windows users must avoid 3.14 due to a transitive pywin32 dependency failure.
Is there a Docker↗ Bright Coding Blog image available?
The README does not document one. Installation is via UVX or source with uv sync.
How does device auto-detection work?
The server queries adb devices on first tool invocation, preferring physical devices over emulators. Explicit configuration overrides this.
What's the license? MIT License. See the repository's LICENSE file for full terms.
Can I contribute? Yes—the README references CONTRIBUTING guidelines for development setup and PR requirements.
Conclusion
CursorTouch/Android-MCP solves a specific, increasingly relevant problem: giving LLM agents deterministic, low-latency control over Android devices without custom model training or computer-vision infrastructure. Its MCP-native design, lazy connection handling, and explicit BYO-model policy make it a pragmatic choice for teams already invested in the Model Context Protocol ecosystem—particularly those using Claude Desktop or OpenCode.
The 736-star project is not a universal replacement for established testing frameworks like Appium, nor does it attempt to be. It is best suited for agent builders, accessibility researchers, and QA engineers who need their LLM to operate real mobile UIs through a clean, standardized interface. The MIT license and active maintenance (last commit July 2026) reduce adoption risk for production experiments.
Ready to connect your LLM to Android? Clone the repository, verify your ADB setup, and configure your MCP client: https://github.com/CursorTouch/Android-MCP
