Skip to main content
Glama
Android-MCP

Android-MCP

by buhozurdo
README.md
# Android-MCP: Universal Android Control for LLM Agents

An isolated **Android environment in Docker (`redroid`)** coupled with a **Model Context Protocol (MCP)** server over HTTP/SSE and stdio. It enables any AI agent or LLM (Claude Desktop, Cursor, LangChain, custom frameworks) to operate the entire mobile deviceβ€”installing apps, navigating UI hierarchies, reading notifications, and executing gesturesβ€”without building brittle per-application integrations.

---

## πŸ›οΈ Architecture

```text
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”      HTTP / SSE / Stdio     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   MCP Client / Agent    β”‚ ◄─────────────────────────► β”‚     MCP Server (Python)     β”‚
β”‚ (Claude, Cursor, etc.)  β”‚     http://localhost:8000   β”‚  FastMCP + UI Token Parser  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                             β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                                                       β”‚ ADB (TCP :5555)
                                                                       β–Ό
                                                        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                                                        β”‚  Virtual Android (redroid)  β”‚
                                                        β”‚  Native Kernel + /data vol  β”‚
                                                        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```

### Why this approach?
* **Single Integration ("Android-as-a-Tool")**: The LLM interacts with any application just like a human user, eliminating the need to maintain bespoke REST/GraphQL connectors per service.
* **Token-Optimized UI Parsing**: Instead of sending expensive screenshots or raw 100KB–300KB XML dumps from `uiautomator`, the server parses and compresses the hierarchy into lightweight JSON (~2-5KB) providing actionable elements and exact centroids `(cx, cy)` for zero-math tapping.
* **Disposable Sandbox**: The Android OS state lives in an isolated volume (`/data`), enabling clean resets to a pristine snapshot in seconds.
* **Enterprise Guardrails & Evals**: Built-in anti-SSRF protection for APK installations, ADB shell injection defense, and PII masking for OTP/2FA notification retrieval.

---

## πŸ“‹ Prerequisites

* **Operating System**: Linux (recommended Ubuntu/Debian) with Android kernel module support, or macOS / Windows with a native Android emulator or physical device.
* **Docker & Docker Compose v2+** (for redroid virtual stack).

Enable required kernel modules on Linux hosts:
```bash
sudo apt install -y linux-modules-extra-$(uname -r)
sudo modprobe binder_linux devices="binder,hwbinder,vndbinder"
sudo modprobe ashmem_linux
```

> **Note for macOS / Windows users:** Docker on macOS and Windows does not expose the Android kernel modules required by redroid. In that case, run a local Android emulator (Android Studio / Genymotion) or connect a physical device via USB, then point the MCP server to `localhost:5555` or your host emulator port.

---

## πŸš€ Quickstart

### 1. Clone and Install
```bash
git clone https://github.com/buhozurdo/android-as-a-tool.git
cd android-as-a-tool

# Install package and dependencies
pip install -e ".[mcp,test]"
```

### 2. Run Environment Doctor
Check that your environment, ADB bridge, and security guardrails are operational:
```bash
python skills/android-doctor/scripts/doctor.py
```

### 3. Launch MCP Server
Run locally over standard I/O (compatible with Claude Desktop, Cursor, etc.):
```bash
android-mcp
```
Or start via Docker Compose:
```bash
docker compose up -d --build
```
The MCP server endpoint will be available at `http://localhost:8000/mcp`.

---

## πŸ› οΈ MCP Tools Catalog

### Application Lifecycle

| Tool | Parameters | Description |
|---|---|---|
| `install_apk` | `source: str` | Installs an `.apk` from a local path or validated remote URL (anti-SSRF protected). |
| `list_apps` | `third_party_only: bool` | Lists installed application package names on the device. |
| `launch_app` | `package: str` | Launches an application directly by package name using launcher intent resolution. |
| `uninstall_app` | `package: str` | Uninstalls an application package from the device. |

### UI Navigation & Interaction

| Tool | Parameters | Description |
|---|---|---|
| `get_screen_elements` | `clickable_only: bool` | Returns compressed UI elements JSON with text, resource ID, and `(cx, cy)` centroids. |
| `tap` | `x: int, y: int` | Taps at specific screen coordinates `(x, y)`. |
| `long_press` | `x: int, y: int, duration_ms: int` | Holds a touch at `(x, y)` for `duration_ms` milliseconds. |
| `type_text` | `text: str` | Types text into the currently focused input field with shell escaping. |
| `swipe` | `direction: str` | Swipes the screen in a given direction (`up`, `down`, `left`, `right`). |
| `press_key` | `key: str` | Sends hardware navigation keyevents (`HOME`, `BACK`, `ENTER`, `APP_SWITCH`). |

### Context & Perception

| Tool | Parameters | Description |
|---|---|---|
| `take_screenshot` | β€” | Captures device display as a Base64-encoded PNG (for WebViews or visual verification). |
| `get_notifications` | β€” | Reads active system notifications with automated PII redaction and OTP extraction. |

---

## πŸ”Œ Connecting MCP Clients

### Claude Desktop
Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "android-device": {
      "command": "android-mcp",
      "env": {
        "ANDROID_ADB_HOST": "localhost",
        "ANDROID_ADB_PORT": "5555"
      }
    }
  }
}
```

### Remote HTTP / SSE Client (Cursor, Custom Agents)
```json
{
  "mcpServers": {
    "android-device": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

---

## πŸ›‘οΈ Enterprise Security Guardrails

Android-MCP integrates a zero-dependency safety engine in `guardrails/`:
* **Anti-SSRF URL Validation**: Rejects `install_apk` downloads targeting cloud metadata services (`169.254.169.254`, `metadata.google.internal`), loopback addresses, and private RFC 1918 subnets.
* **ADB Shell Injection Defense**: Intercepts command chaining (`rm -rf`, `reboot`, subshells `$()`, backticks, pipes) in `type_text`.
* **PII Sanitization**: Redacts credit card numbers and personal emails in notifications, keeping 2FA/OTP tokens intact for automated verification flows.
* **JSON Schema Verification**: Enforces valid JSON formatting on structured outputs before dispatching them to LLMs.

---

## πŸ§ͺ Evaluation Framework & Benchmarks

Run automated benchmarks to evaluate security, UI centroid math, and OTP retention:

```bash
# Run evaluations and generate Markdown report in analysis-reporte/
python evals/evaluators/eval_runner.py --report
```

---

## 🩺 Agent Skills

Modular skills located in `skills/` allow agents and developers to audit and monitor the environment:
* **`code-analyzer`**: Audits codebase compliance against Quality Gates (Gate 1 "Optimal and Acceptable", Gate 2 "Well-Crafted").
  ```bash
  python skills/code-analyzer/scripts/analyze.py
  ```
* **`android-doctor`**: Performs health checks on ADB connectivity, screen resolution, and guardrails.
  ```bash
  python skills/android-doctor/scripts/doctor.py
  ```

---

## πŸ§ͺ Running Tests

Run the full pytest suite (compatible with mock simulation mode without a running device):

```bash
python -m pytest -v
```

---

## πŸ“ Repository Structure

```text
android-as-a-tool/
β”œβ”€β”€ AGENTS.md               # Quality protocols & agent directives (Gate 1 & Gate 2)
β”œβ”€β”€ RELEASE.md              # Branching strategy, checklist & release notes
β”œβ”€β”€ pyproject.toml          # Modern PEP 517/518 build configuration
β”œβ”€β”€ src/android_mcp/        # Core package
β”‚   β”œβ”€β”€ adb_client.py       # ADB bridge wrapper with deterministic mock mode
β”‚   β”œβ”€β”€ server.py           # FastMCP / MCPServer tool registry
β”‚   └── ui_parser.py        # Token-compact UI hierarchy compressor
β”œβ”€β”€ guardrails/             # Security engine (Anti-SSRF, PII, Shell defense)
β”œβ”€β”€ evals/                  # Automated eval benchmarks and runner
β”œβ”€β”€ skills/                 # Agent diagnostic and audit skills
└── tests/                  # Unit and integration test suite
```

---

## πŸ“„ License
[MIT](LICENSE) Β© BuhoZurdo Team