---
title: "Phonegang"
description: "Android phone automation over USB using accessibility trees. CLI, Python API, and MCP server for Claude Code."
canonical_url: "https://2389.ai/products/phonegang/"
last_updated: "2026-03-17T11:10:28-05:00"
doc_version: "1.0"
date: 2025-10-13
product_type: "Tool"
tags: ["android", "automation", "accessibility", "mcp", "cli", "usb", "adb", "agents", "open-source"]
---

# Phonegang

> Android phone automation over USB using accessibility trees. CLI, Python API, and MCP server for Claude Code.


Phonegang controls Android phones over USB by reading the accessibility tree — the same structured data that screen readers use. Instead of matching pixels or hardcoding coordinates, you find elements by their text, resource ID, or content description. It ships as a CLI, a Python library, and an MCP server that lets Claude Code tap your phone directly.

## Install

```bash
git clone https://github.com/2389-research/phonegang.git
cd phonegang
uv sync
```

Requires Python 3.10+, an Android device with USB debugging enabled, and ADB on your PATH.

## What it does

**CLI commands** cover the common operations: `phonegang tap-text "Login"`, `phonegang type "hello"`, `phonegang screenshot`, `phonegang scroll-to "Settings"`. You can also dump the raw UI tree, list connected devices, manage apps, and navigate with back/home.

**Python API** gives you `DeviceManager`, `ADBDevice`, and `DeviceController`. Connect to a device, refresh the accessibility tree, find elements by text/class/resource-id/custom predicates, then tap, type, scroll, or wait for elements to appear. The tree object supports chained queries — find all buttons, filter by size, grab the clickable ones.

**MCP server** exposes high-level tools (`get_screen`, `tap`, `type_text`, `wait_for`) and low-level tools (`tap_xy`, `swipe`, `press_key`, `get_ui_dump`) over MCP. Add it to your Claude Code config and ask Claude to interact with your phone in natural language.

## How it works

Four layers, bottom to top:

1. **ADB layer** — wraps `adb-shell` for raw device communication (shell commands, file push/pull, input events)
2. **Accessibility tree parser** — parses `uiautomator` XML dumps into queryable Python objects with bounds, text, resource IDs, and click state
3. **Device controller** — combines ADB and the parsed tree for high-level operations (find-and-tap, scroll-to-text, wait-for-element)
4. **CLI / MCP** — Click-based CLI and MCP server that expose the controller to humans and AI agents

## Requirements

- Python 3.10+
- Android device with USB debugging enabled
- ADB (Android Debug Bridge) — comes with Android SDK or install standalone
- `adb-shell`, `click`, `lxml` (installed automatically via `uv sync`)


## Sitemap

Parent: [Products](https://2389.ai/products/index.md)

Related pages in this section:

- [Skills Marketplace](https://2389.ai/products/skills-marketplace/index.md)
- [Mammoth](https://2389.ai/products/mammoth/index.md)
- [BotBoard](https://2389.ai/products/botboard/index.md)
- [Smasher](https://2389.ai/products/smasher/index.md)
- [Jeff](https://2389.ai/products/jeff/index.md)
- [Mux](https://2389.ai/products/mux/index.md)
- [ISH](https://2389.ai/products/ish/index.md)
- [Coven](https://2389.ai/products/coven/index.md)
- [Soloclaw](https://2389.ai/products/soloclaw/index.md)
- [ccvault](https://2389.ai/products/ccvault/index.md)


Site index: [llms.txt](https://2389.ai/llms.txt) · [sitemap.md](https://2389.ai/sitemap.md) · [HTML](https://2389.ai/products/phonegang/)