https://github.com/CursorTouch/Android-MCP
Lightweight MCP Server for interacting with Android Operating System.
https://github.com/CursorTouch/Android-MCP
ai android automation mcp-server
Last synced: 6 months ago
JSON representation
Lightweight MCP Server for interacting with Android Operating System.
- Host: GitHub
- URL: https://github.com/CursorTouch/Android-MCP
- Owner: CursorTouch
- License: mit
- Created: 2025-06-11T08:06:30.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-09-02T07:48:14.000Z (10 months ago)
- Last Synced: 2025-09-02T09:28:55.987Z (10 months ago)
- Topics: ai, android, automation, mcp-server
- Language: Python
- Homepage:
- Size: 88.9 KB
- Stars: 44
- Watchers: 0
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
🤖 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.
## ✨ 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", ""` 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",
"",
"run",
"android-mcp"
]
}
}
}
```
> **Note:** Replace `` with the full path to your cloned directory. Add `"--device", ""` 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},
}
```