Android-MCP

🤖 Android MCP

Android-MCP is a lightweight, open-source tool that bridge between AI agents and Android devices. Running as an MCP server, it lets LLM agents perform real-world tasks such as app navigation, UI interaction and automated QA testing without relying on traditional computer-vision pipelines or preprogramed scripts.

https://github.com/user-attachments/assets/cf9a5e4e-b69f-46d4-8487-0f61a7a86d67

✨ Features

• Native Android Integration
  Interact with UI elements via ADB and the Android Accessibility API: launch apps, tap, swipe, input text, and read view hierarchies.

• Bring Your Own LLM/VLM
  Works with any language model, no fine-tuned CV model or OCR pipeline required.

• Rich Toolset for Mobile Automation
  Pre-built tools for gestures, keystrokes, capture, device state, shell commands execution.

• Real-Time Interaction
  Typical latency between actions (e.g., two taps) ranges 2-4s depending on device specs and load.

Supported Operating Systems

• Android 10+

Installation

📦 Prerequisites

• Python 3.13
• ADB (Android Debug Bridge)
• Android 10+ (Emulator/ Android Device)

📲 Testing ADB Connection

Before running the server, ensure your Android device is connected and recognized by ADB:

1. Connect your Android device via USB or ensure your emulator is running.
2. Open a terminal and run:

   adb devices
   

3. You should see your device listed:

   List of devices attached
   R38M30XXXXX   device
   

   The serial number will differ per device. Emulators show serials like emulator-5554. If the list is empty or shows "unauthorized", check your USB debugging settings on the device.

For WiFi ADB, connect the device first:

adb connect 192.168.1.3:5555
adb devices

🏁 Getting Started

You can run the Android MCP server using UVX (recommended) or UV (for local development).

Option 1: UVX (Recommended)

No need to install dependencies manually. Just configure Claude Desktop:

Windows note: Use Python 3.13 for uvx on Windows. Python 3.14 currently fails to resolve a transitive pywin32 dependency used by the MCP stack.

1. Locate your config file

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the configuration

   {
     "mcpServers": {
       "android-mcp": {
         "command": "uvx",
         "args": [
           "--python",
           "3.13",
           "android-mcp"
         ]
       }
     }
   }
   

   Note: The server starts first and connects lazily when a tool runs. If no device is specified, it auto-detects connected devices and prefers physical devices over emulators. Use --device <serial> or the ANDROID_MCP_DEVICE environment variable to target a specific device.

   Configure a specific 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"
         }
       }
     }
   }
   

   Or pass explicit flags:

   {
     "mcpServers": {
       "android-mcp": {
         "command": "uvx",
         "args": [
           "--python",
           "3.13",
           "android-mcp",
           "--wifi",
           "192.168.1.3"
         ]
       }
     }
   }
   

Option 2: UV Mode (Local Development)

1. Clone and Install

   git clone https://github.com/CursorTouch/Android-MCP.git
   cd Android-MCP
   uv sync
   

2. Configure Claude Desktop

   {
     "mcpServers": {
       "android-mcp": {
         "command": "uv",
         "args": [
           "--directory",
           "</PATH/TO/Android-MCP>",
           "run",
           "android-mcp"
         ]
       }
     }
   }
   

   Note: Replace </PATH/TO/Android-MCP> with the full path to your cloned directory. You can also add "--device", "<YOUR_DEVICE_serial>", "--wifi", "192.168.1.3", or "--usb" to control device selection. uv sync follows the repo's .python-version, so local development uses Python 3.13 by default.

Option 3: OpenCode

You can also use Android-MCP with OpenCode. After cloning and installing the repo (see Option 2), add the server as a local MCP in your OpenCode config (opencode.json):

{
  "mcp": {
    "android-mcp": {
      "type": "local",
      "command": ["uv", "--directory", "</PATH/TO/Android-MCP>", "run", "android-mcp"]
    }
  }
}

Note: Replace </PATH/TO/Android-MCP> with the full path to your cloned directory. As with UV mode, you can append "--device", "--wifi", "--usb", etc. to the command array to control device selection.

🔌 Device Selection

Android-MCP resolves devices lazily when a tool is called, so the MCP server can start even if no device is available yet.

• --device RFCN2013V8D: connect to a specific USB serial
• --device 192.168.1.3:5555: connect to a specific WiFi ADB target
• --wifi 192.168.1.3: use WiFi and auto-append port 5555
• --usb: auto-detect the first USB-connected device
• --usb RFCN2013V8D: use a specific USB device
• --connection wifi: prefer the first available WiFi ADB device
• --connection usb: prefer the first available USB device

Supported environment variables:

• ANDROID_MCP_DEVICE: explicit serial or host:port
• ANDROID_MCP_CONNECTION: auto, usb, or wifi
• ANDROID_MCP_HOST: WiFi host, with :5555 added automatically when omitted

If nothing is configured, Android-MCP will use the first available ADB device reported by adb devices. If none are available, tool calls return a configuration error instead of crashing