Android Mcp

Android MCP

あらゆる AI エージェントから Android を完全に操作 — Claude、OpenCode、Windsurf、Cursor… カテゴリー別の MCP ツール 7 個 · 90fps のライブビューアー · WiFi ADB · インストールするアプリは不要

---

クイックデモ

android_screen(action="screenshot")                          # PNG capture
android_screen(action="ocr")                                 # visible text
android_interact(action="tap", params={"x": 540, "y": 960}) # tap
android_interact(action="find", params={"text": "Send"})     # find + tap
android_system(action="battery")                             # battery info
android_screen(action="viewer")                              # 90fps interactive window on PC

---

アーキテクチャ

AI Agent (Claude / OpenCode / Windsurf / Cursor…)
        ↓  MCP Protocol (stdio)
    server.py          ← 7 categorical tools
        ↓
    device_manager.py  ← device selection, multi-device
        ↓
    backends/
        ├── adb_backend.py       ← PRIMARY  : uiautomator2 + direct ADB
        └── companion_backend.py ← FALLBACK : Flutter app WebSocket
        ↓
    N Android phones / emulators

ADB バックエンド（プライマリ） — 開発者モードが有効なデバイスであれば、どれでも動作します。 スマートフォンにインストールするものはありません。uiautomator2 と ADB コマンドを使用します。

コンパニオンバックエンド（フォールバック） — ネットワーク上で ADB を利用できない場合に使用できる、オプションの Flutter アプリです。

---

必要条件

• Python 3.10 以降
• PATH に ADB があること（winget install Google.PlatformTools）
• Android：開発者モード＋USB デバッグ（または WiFi デバッグ）

---

インストール

git clone https://github.com/Steph-ux/android-mcp
cd android-mcp
pip install -r requirements.txt

# Initialize uiautomator2 (once per device)
python -m uiautomator2 init

90fps ライブビューアー（任意）

winget install Genymobile.scrcpy
python viewer.py

---

MCP の設定

# Generate the correct JSON for your AI client
python mcp_config.py --client claude     # Claude Desktop
python mcp_config.py --client opencode  # OpenCode
python mcp_config.py --client windsurf  # Windsurf
python mcp_config.py --client cursor    # Cursor
python mcp_config.py --write            # write directly to config files

Claude Desktop の設定例（claude_desktop_config.json）：

{
  "mcpServers": {
    "android-mcp": {
      "command": "C:/Python312/python.exe",
      "args": ["D:/path/to/android-mcp/server.py"],
      "type": "stdio"
    }
  }
}

---

USB を使わずに WiFi 接続（Android 11 以降）

# On the phone: Settings → Developer options → Wireless debugging → Pair device
adb pair 192.168.1.42:38765    # enter the code shown on the phone
adb connect 192.168.1.42:5555

詳しいガイド → WIFI_PAIRING.md

---

7 つの MCP ツール

呼び出し形式：android_xxx(action="...", params={...}, device_id="serial") device_id は常に省略可能です（現在選択されているデバイスを使用します）。

---

android_device — デバイス管理

アクション	パラメーター	説明
list	—	接続されているすべてのデバイス（USB、WiFi、エミュレーター）
select	serial	デフォルトのデバイスを設定
connect	host, port	WiFi ADB 接続
disconnect	—	現在の WiFi デバイスを切断
info	—	モデル、OS、解像度、密度
status	—	デバイスは接続され、使用可能ですか？
setup	—	アニメーション、スリープ解除維持、ATX エージェントを設定

---

android_screen — キャプチャとストリーミング

アクション	パラメーター	説明
screenshot	—	PNG キャプチャ（FLAG_SECURE を回避）→ 画像
region	x y width height	指定範囲をキャプチャ → 画像
size	—	{width, height}
is_on	—	画面は点灯していますか？
wake	—	画面を点灯
start_stream	—	ADB ストリームを開始（約 16fps）
stop_stream	—	ストリームを停止
live_frame	—	ストリームの最新フレーム → 画像
ocr	lang	表示されているテキストを抽出（Tesseract）
find_image	template_b64 threshold	テンプレートマッチング（OpenCV）
viewer	fps bitrate no_control	PC で scrcpy の 90fps ウィンドウを起動

---

android_interact — タッチ、キーボード、UI

アクション	パラメーター	説明
tap	x y	タップ
double_tap	x y	ダブルタップ
long_press	x y duration_ms	長押し
swipe	x1 y1 x2 y2 duration_ms	スワイプ
drag	x1 y1 x2 y2 duration_ms	ドラッグ＆ドロップ
pinch	x y scale duration_ms	ピンチズーム
multi_touch	points	マルチフィンガージェスチャー
type	text	テキストを入力
clear	—	アクティブなフィールドをクリア
submit	text	テキストを入力して Enter
key	key	システムキー（HOME、BACK、ENTER、VOLUME_UP…）
combo	keys	キーの組み合わせ（キーコード）
hierarchy	—	UI の完全な XML ツリー（uiautomator2）
find	text partial_match	要素を検索してタップ
wait	text timeout partial_match	要素が表示されるまで待機
scroll	text direction max_swipes	要素までスクロール
assert	text partial_match	テキストが表示されていることを確認

---

android_app — アプリケーション

アクション	パラメーター	説明
launch	package	アプリを起動
close	package	アプリを強制停止
list	include_system	インストール済みアプリを一覧表示
install	apk_path	PC から APK をインストール
uninstall	package	アプリをアンインストール
current	—	フォアグラウンドのアプリパッケージ
url	url	URL を開く
intent	action uri package extras	Android インテントを送信
settings	section	システム設定を開く（main wifi bluetooth display…）

---

android_files — ファイル

アクション	パラメーター	説明
push	local_path remote_path	PC → phone
push_b64	remote_path data	Base64 → phone
pull	remote_path local_path	Phone → PC
pull_b64	remote_path	Phone → base64
list	directory	ディレクトリの内容を一覧表示

---

android_system — システムとネットワーク

アクション	パラメーター	説明
shell	command	ADB シェルコマンド
logs	lines package	Logcat
battery	—	バッテリー残量と充電状態
clipboard_get	—	クリップボードを読み取る
clipboard_set	text	クリップボードに書き込む
volume	level stream	音量を設定する
rotation	rotation	画面の回転（0-3）
wifi	enabled	WiFi のオン／オフ
bluetooth	enabled	Bluetooth のオン／オフ
mobile_data	enabled	モバイルデータのオン／オフ
notifications	—	アクティブな通知
gps	lat lng	GPS 位置情報を偽装する
sensors	sensor	加速度計、ジャイロ、光センサーなど
wifi_list	—	利用可能な WiFi ネットワーク
wifi_connect	ssid password	WiFi に接続する
contacts	search limit	連絡先を読み取る
sms	to message	SMS を送信する（スマートフォンでの確認が必要）

---

android_automation — バッチとマクロ

アクション	パラメーター	説明
batch	actions stop_on_error	1 回の呼び出しで N 個のアクションを実行する
macro_start	name	マクロの記録を開始する
macro_record	action …params	マクロにアクションを追加する
macro_stop	—	マクロを保存する
macro_list	—	保存済みマクロを一覧表示する
macro_replay	name delay_ms	マクロを再生する
macro_delete	name	マクロを削除する

---

ライブビューアー — scrcpy 90fps

python viewer.py                  # auto-detect device, 90fps, interactive
python viewer.py --fps 60         # 60fps
python viewer.py --record         # record to .mp4
python viewer.py --record out.mp4 # named output file
python viewer.py --multi          # one viewer per connected device
python viewer.py --no-control     # read-only mode

操作	アクション
左クリック	タップ
ドラッグ	スワイプ
右クリック	BACK
スクロール	スクロール
Alt+H	HOME
Alt+S	スクリーンショット → PC のクリップボード
Alt+F	全画面表示
Alt+R	回転

---

テスト

# Unit tests (no device required)
pytest tests/test_server_unit.py -v      # 94 tests

# Integration tests (ADB device required)
pytest tests/test_integration.py -v

---

プロジェクト構成

android-mcp/
├── server.py              # MCP server — 7 tools
├── viewer.py              # scrcpy 90fps interactive viewer
├── mcp_config.py          # JSON config generator
├── device_manager.py      # Multi-device management
├── relay.py               # ⚠️ LEGACY — companion fallback only
├── requirements.txt
├── pyproject.toml
├── WIFI_PAIRING.md
├── backends/
│   ├── adb_backend.py     # Primary backend (uiautomator2 + ADB)
│   └── companion_backend.py  # Fallback backend (Flutter app)
├── examples/
│   ├── agent_loop.py      # Autonomous automation loop
│   └── whatsapp_auto.py   # WhatsApp automation example
└── tests/
    ├── conftest.py
    ├── test_server_unit.py   # 94 unit tests
    └── test_integration.py   # Real device tests

---

使用例

# WhatsApp — send a message
await android_app("launch", {"package": "com.whatsapp"})
await android_interact("find", {"text": "Alice"})
await android_interact("type", {"text": "Hello!"})
await android_interact("key",  {"key": "ENTER"})

# Batch in a single call
await android_automation("batch", {"actions": [
    {"action": "key",  "key": "HOME"},
    {"action": "tap",  "x": 540, "y": 200},
    {"action": "type", "text": "search query"},
    {"action": "key",  "key": "ENTER"},
]})

# Macro: record + replay
await android_automation("macro_start",  {"name": "login"})
await android_automation("macro_record", {"action": "tap",  "x": 540, "y": 400})
await android_automation("macro_record", {"action": "type", "text": "password"})
await android_automation("macro_stop")
await android_automation("macro_replay", {"name": "login"})

すべての使用例については、examples/whatsapp_auto.py と examples/agent_loop.py を参照してください。

---

ライセンス

MIT