🤖 android-mcp

A standard Model Context Protocol (MCP) server that enables AI agents (Claude Desktop, Cursor, Antigravity, and autonomous LLMs) to directly control, inspect, and automate Android devices, Waydroid, and AVD emulators over ADB.

🏗️ Architecture

┌───────────────────────────────┐
│ AI Client (Claude / Cursor)   │
└──────────────┬────────────────┘
               │ JSON-RPC (stdio)
               ▼
┌───────────────────────────────┐
│         android-mcp           │
│   (Model Context Protocol)    │
└──────────────┬────────────────┘
               │ ADB (Android Debug Bridge)
               ▼
┌───────────────────────────────┐
│ Android Device / Waydroid     │
└───────────────────────────────┘

Related MCP server: scrcpy-mcp

✨ Features

• 👁️ Vision Support: Captures instant PNG screenshots directly into the LLM's context window.

• 🎯 Smart UI Click: Parse on-screen XML hierarchy (uiautomator) and click buttons by human label or text (e.g. android_click_by_text("Sign In")).

• 👆 Gestures & Input: Full support for precise taps, multi-point swipes/drags, and text typing.

• ⌨️ Hardware Keys: Send system keys (BACK, HOME, ENTER, POWER, VOLUME).

• 📱 App Management: Launch, stop, and inspect installed third-party apps.

• ⚡ Zero External Pip Dependencies: Built entirely on Python standard library and ADB.

🚀 Quick Setup

1. Prerequisites

Ensure adb is installed and your device or Waydroid container is connected:

# Verify ADB sees your device or emulator
adb devices

2. Connect to Claude Desktop

Open your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Add android-mcp to your mcpServers:

{
  "mcpServers": {
    "android": {
      "command": "python3",
      "args": ["/path/to/android-mcp/run_server.py"]
    }
  }
}

3. Connect to Cursor / Other MCP Clients

Add an entry pointing to python3 /path/to/android-mcp/run_server.py in your client's MCP settings tab.

🛠️ Available MCP Tools

💬 Example Prompts for Your AI

Once connected in Claude or Cursor, you can ask your AI naturally:

• "Check if my Android device is connected."

• "Take a screenshot of Android and tell me what screen is currently open."

• "Tap the Settings button on screen."

• "Type 'hello world' into the active search bar and press Enter."

• "Go back to the Home screen."

⚙️ Environment Variables (Optional)

🛡️ License

Distributed under the MIT License. Free for personal and commercial use.