Phonegang はUSBを介してAndroid端末をアクセシビリティツリーで操作します。スクリーンリーダーが使う構造化データと同じものです。ピクセルのマッチングや座標のハードコーディングではなく、テキスト、リソースID、コンテンツ説明で要素を見つけます。CLI、Pythonライブラリ、Claude Code から直接スマートフォンを操作できるMCPサーバーとして提供されます。

インストール

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

Python 3.10+、USBデバッグが有効なAndroid端末、PATHにADBが必要です。

できること

CLIコマンドで一般的な操作をカバーします: phonegang tap-text "Login"、phonegang type "hello"、phonegang screenshot、phonegang scroll-to "Settings"。生のUIツリーのダンプ、接続デバイスの一覧表示、アプリ管理、back/homeナビゲーションも可能です。

Python API で DeviceManager、ADBDevice、DeviceController を使えます。デバイスに接続し、アクセシビリティツリーをリフレッシュし、テキスト/クラス/リソースID/カスタム述語で要素を検索し、タップ、入力、スクロール、または要素の出現を待機します。ツリーオブジェクトはチェーンクエリをサポートします — すべてのボタンを検索し、サイズでフィルタリングし、クリック可能なものを取得。

MCPサーバーで高レベルツール (get_screen、tap、type_text、wait_for) と低レベルツール (tap_xy、swipe、press_key、get_ui_dump) をMCP経由で公開します。Claude Codeの設定に追加すれば、自然言語でスマートフォンを操作できます。

仕組み

下から上へ4つのレイヤー:

ADBレイヤー — adb-shell をラップして生のデバイス通信 (シェルコマンド、ファイルプッシュ/プル、入力イベント) を処理
アクセシビリティツリーパーサー — uiautomator XMLダンプを、バウンド、テキスト、リソースID、クリック状態を持つクエリ可能なPythonオブジェクトに変換
デバイスコントローラー — ADBと解析済みツリーを組み合わせて高レベル操作を実現 (find-and-tap、scroll-to-text、wait-for-element)
CLI / MCP — コントローラーを人間とAIエージェントに公開するClickベースのCLIとMCPサーバー

必要要件

Python 3.10+
USBデバッグが有効なAndroid端末
ADB (Android Debug Bridge) — Android SDKに付属またはスタンドアロンでインストール
adb-shell、click、lxml (uv sync で自動インストール)