Android Mcp

Android MCP

通过任意 AI Agent 完全控制 Android — Claude、OpenCode、Windsurf、Cursor…… 7 个分类 MCP 工具 · 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+
• ADB 已加入 PATH（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	—	型号、操作系统、分辨率、密度
status	—	设备是否已连接并就绪？
setup	—	配置动画、保持唤醒、ATX Agent

---

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 Intent
settings	section	打开系统设置（main wifi bluetooth display…）

---

android_files — 文件

操作	参数	描述
push	local_path remote_path	电脑 → 手机
push_b64	remote_path data	Base64 → 手机
pull	remote_path local_path	手机 → 电脑
pull_b64	remote_path	手机 → Base64
list	directory	列出目录内容

---

android_system — 系统与网络

操作	参数	描述
shell	command	ADB shell 命令
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	一次调用运行 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

控件	操作
左键单击	点击
拖动	滑动
右键单击	返回
滚动	滚动
Alt+H	主页
Alt+S	截图 → 电脑剪贴板
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