Android MCP

<div align="center"> <h1>🤖 Android MCP</h1> <a href="https://github.com/CursorTouch/Android-MCP/blob/main/LICENSE"> <img src="https://img.shields.io/badge/license-MIT-green" alt="License"> </a> <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python"> <img src="https://img.shields.io/badge/platform-Android%2010+-blue" alt="Platform"> <img src="https://img.shields.io/github/last-commit/CursorTouch/Android-MCP" alt="Last Commit"> <br> <a href="https://x.com/CursorTouch"> <img src="https://img.shields.io/badge/follow-%40CursorTouch-1DA1F2?logo=twitter&style=flat" alt="Follow on Twitter"> </a> <a href="https://discord.com/invite/Aue9Yj2VzS"> <img src="https://img.shields.io/badge/Join%20on-Discord-5865F2?logo=discord&logoColor=white&style=flat" alt="Join us on Discord"> </a> </div> <br> **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.10+ - 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: ```shell adb devices ``` 3. You should see your device listed: ``` List of devices attached emulator-5554 device ``` If the list is empty or shows "unauthorized", check your USB debugging settings on the device. ### 🏁 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: 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** ```json { "mcpServers": { "android-mcp": { "command": "uvx", "args": [ "android-mcp" ] } } } ``` > **Note:** By default, it connects to `emulator-5554`. To connect to a specific device, add `"--device", "<YOUR_DEVICE_serial>"` to the args list. #### Option 2: UV Mode (Local Development) 1. **Clone and Install** ```shell git clone https://github.com/CursorTouch/Android-MCP.git cd Android-MCP uv sync ``` 2. **Configure Claude Desktop** ```json { "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. Add `"--device", "<YOUR_DEVICE_serial>"` to args to target a specific device. 3. **Restart the Claude Desktop** Restart your Claude Desktop. You should see "android-mcp" listed as an available integration. That's it, now you're ready to start controlling your Android device with natural language. For troubleshooting tips (log locations, common ADB issues), see the [MCP docs](https://modelcontextprotocol.io/quickstart/server#android-mcp-integration-issues). --- ## 🛠️ Available Tools Claude can access the following tools to interact with Windows: - `State-Tool`: To understand the state of the device. - `Click-Tool`: Click on the screen at the given coordinates. - `Long-Click-Tool`: Perform long click on the screen at the given coordinates. - `Type-Tool`: Type text on the specified coordinates (optionally clears existing text). - `Swipe-Tool`: Perform swipe from one location to other. - `Drag-Tool`: Drag from one point to another. - `Press-Tool`: To press the keys on the mobile device (Back, Volume Up, ...etc). - `Wait-Tool`: Pause for a defined duration. - `State-Tool`: Combined snapshot of active apps and interactive UI elements. - `Notification-Tool`: To access the notifications seen on the device. - `Shell-Tool`: To execute shell commands on the android device. ## ⚠️ Caution Android-MCP can execute arbitrary UI actions on your mobile device. Use it in controlled environments (emulators, test devices) when running untrusted prompts or agents. ## 🪪 License This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. ## 🤝 Contributing Contributions are welcome! Please read [CONTRIBUTING](CONTRIBUTING) for dev setup and PR guidelines. Made with ❤️ by [CursorTouch](https://github.com/cursortouch), developers: [Jeomon George](https://github.com/jeomon), [Muhammad Yaseen](https://github.com/mhmdyaseen) ## Citation ```bibtex @misc{ author = {cursortouch}, title = {Android-MCP}, year = {2025}, publisher = {GitHub}, howpublished = {\url{https://github.com/CursorTouch/Android-MCP}}, note = {Lightweight open-source bridge between LLM agents and Android}, } ```