phone-control-mcp

Let any AI agent drive your Android phone. One codebase, two interfaces:

• MCP server (server.py, stdio) — plug into Codex, Claude Desktop, Cursor, or any MCP client and get 28 phone-control tools, including screenshots returned as real images the model can see.

• Zero-dependency CLI (phone_control.py) — any agent that can run a shell command can control the phone; also great for humans and cron jobs.

Built on ADB. Pure Python standard library for the core; only the optional MCP layer needs pip install mcp.

简体中文文档 →

Why it's fast

AI phone-control feels slow when every action is a round trip. This project attacks latency on both layers:

Transport layer (measured on vivo V2408A · Android 16 · Windows 11 · USB):

† The remaining ~2 s is the on-device uiautomator Java startup — a fixed Android cost; our own overhead is now ~200 ms.

• Persistent shell session — one long-lived adb shell with a marker protocol instead of spawning adb.exe + handshake + device sh per command. Auto-reconnects, auto-falls back to one-shot mode on anything suspicious (multi-line commands, unbalanced quotes, stdin-reading commands are isolated with </dev/null).

• Single-roundtrip UI fetch — dump → cat → rm merged into one exec-out call, no temp files, no adb pull.

• Merged probes — device_info collects everything in one shell script.

• Keep-alive — the MCP server pings the device every 45 s so Windows USB selective-suspend doesn't drop it.

Agent layer (the bigger win — every saved tool call is a saved LLM round trip):

• tap_text "Send" — locate a control by on-screen text and tap it in one call.

• wait_for_text — poll until a screen element appears instead of blind sleep.

• run_script — run an entire multi-step flow (open app → wait → tap → type → screenshot) as one tool call.

Related MCP server: android-mcp

Install

Requirements: Python 3.10+, an Android phone with USB debugging enabled.

Windows (one command):

powershell -ExecutionPolicy Bypass -File install.ps1

Creates .venv, installs the MCP SDK, and auto-downloads Google platform-tools (adb) if missing.

Linux / macOS / manual:

python3 -m venv .venv && .venv/bin/pip install "mcp>=1.2"   # only needed for the MCP server
# adb: use your package manager, or set ADB_PATH=/path/to/adb

Phone setup (once): Settings → About phone → tap Build number 7 times → Developer options → enable USB debugging → plug in → choose File transfer → accept the RSA prompt (tick Always allow).

Verify: python phone_control.py doctor — fix hints are printed for every failure mode.

Connect your AI tool

Codex CLI

codex mcp add phone-control -- /path/to/.venv/bin/python /path/to/server.py

Claude Desktop / Cursor / any MCP client

{
  "mcpServers": {
    "phone-control": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/server.py"]
    }
  }
}

DeepSeek Harness (DSH)

• Skill: copy skills/phone-control/ into ~/.dsh/skills/ (or <project>/.dsh/skills/) — hot-reloads into the session skill catalog; edit the entry-point path inside SKILL.md to your checkout.

• Or plain CLI: agents call python phone_control.py <subcommand> through the shell; results are UTF-8 JSON.

Plain shell / cron / you

python phone_control.py screenshot now.png
python phone_control.py tap-text "微信"

The 28 MCP tools

The CLI mirrors every tool (tap-text, wait-for, script, …) — see python phone_control.py --help.

run_script example

[
  {"action": "open", "package": "com.tencent.mm"},
  {"action": "wait_for", "text": "微信", "timeout_s": 15},
  {"action": "tap_text", "text": "通讯录"},
  {"action": "screenshot", "save_path": "contacts.png"}
]

Actions: tap tap_text long_press swipe swipe_screen key text sleep wait_for open stop current_app assert_app screenshot find shell. Each step reports {step, action, ok, result|error}; stops on first error unless stop_on_error=false.

Recipes

Chinese / CJK text input — stock adb shell input text is ASCII-only. Install ADBKeyboard once (python phone_control.py install ADBKeyBoard.apk); afterwards input_text auto-switches IME, types via base64 broadcast, and restores your IME.

Wi-Fi (no cable) — Developer options → Wireless debugging → Pair device with pairing code:

python phone_control.py pair 192.168.1.20:37123 123456
python phone_control.py connect 192.168.1.20:40001

Keep screen awake while plugged (avoids lock-screen interruptions):

python phone_control.py shell "svc power stayon true"

Multiple phones — pass --serial <SN> (CLI) / serial (MCP tools), or set PHONE_SERIAL.

Troubleshooting

Development

python test_mcp.py       # end-to-end MCP smoke test (no device needed) — also runs in CI
python benchmark.py      # latency benchmark (device required)
python regression.py     # 40-check integration suite (device required)

Project layout — deliberately just two modules:

phone_control.py   # core library + CLI, stdlib only
server.py          # MCP server (thin wrapper, mcp SDK v1 & v2 compatible)
install.ps1        # Windows one-shot installer (venv + mcp + platform-tools)
skills/            # DeepSeek Harness skill bundle

Safety

• Destructive operations (uninstall_app, overwriting push_file, arbitrary device_shell) are documented as confirm-first for agents.

• The bundled skill instructs agents to never drive payment/banking screens unprompted and never exfiltrate verification codes or screenshots.

• Everything runs locally over ADB; no telemetry, no cloud.

License

MIT © phone-control-mcp contributors