Metadata-Version: 2.4
Name: iflow-mcp_cursortouch-android-mcp
Version: 0.1.0
Summary: Lightweight MCP Server for Android Operating System
Project-URL: Homepage, https://github.com/CursorTouch/Android-MCP
License: MIT License
        
        Copyright (c) 2025 JEOMON GEORGE
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: android,automation,mcp,mobile
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.14.0
Requires-Dist: ipykernel>=6.30.1
Requires-Dist: pillow>=11.2.1
Requires-Dist: tabulate>=0.9.0
Requires-Dist: uiautomator2>=3.3.1
Description-Content-Type: text/markdown

<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.

## ⚙️ Environment Variables

- `SCREENSHOT_QUANTIZED`: Set to `true` to quantize the screenshot to reduce input tokens.

## ⚠️ 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},
}
```
