android-phone-mcp

代码 Agent 无关的 Android 控制 MCP Server：语义动作 + 验证闭环 + 融合感知。 Any MCP client (Claude Code / Cursor / Cline / 自研 Agent) can control an Android device through semantic tools — no coordinate guessing, every action returns verification evidence.

⚠️ Phase 0 MVP：Phase 0（语义动作 + 验证闭环）已完成真机验收。完整设计见 android-phone-mcp-server-设计文档.md 与 openspec/。

快速开始（开发环境）

# 1. 创建虚拟环境并安装（uv；国内网络请配置镜像）
uv venv .venv
export UV_DEFAULT_INDEX=https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple   # 可选
uv pip install -e ".[dev]"

# 2. 连接 WiFi adb 设备
adb connect <phone-ip>:<port>        # 例如 192.168.1.15:39455
adb devices                          # 确认 device 状态

# 3. 启用开发写权限（默认只读！）
cp .env.example .env

# 4. 启动 MCP server（stdio）
.venv/bin/android-phone-mcp --stdio

# 5. 常用检查
.venv/bin/android-phone-mcp --show-config   # 查看生效配置
.venv/bin/android-phone-mcp --list-tools    # 列出全部 11 个工具

作为 MCP 客户端接入（Python 示例）

import asyncio
from fastmcp import Client
from android_phone_mcp.config import Config
from android_phone_mcp.server import create_server

async def main():
    server = create_server(config=Config(allow_write=True))  # 开发期开写
    async with Client(server) as client:
        r = await client.call_tool("open_settings", {"panel": "about_phone"})
        print(r.data)   # {executed, screen_changed, changed_elements[], screen_hash}

asyncio.run(main())

任意 MCP 客户端（Claude Code / Cursor / Cline / 自研 Agent）均可通过 MCP 协议接入；错误以结构化 JSON 返回（如 WRITE_DISABLED / SELECTOR_AMBIGUOUS + candidates[]），模型可直接读取提示继续操作。

安全模型

开关	环境变量	默认
写操作（tap/输入/安装等）	ANDROID_MCP_ALLOW_WRITE	off（只读）
任意 adb shell	ANDROID_MCP_ALLOW_SHELL	off
每动作超时	ANDROID_MCP_ACTION_TIMEOUT	30s

配置优先级：环境变量 > config.yaml > 内置默认。.env 仅用于本地开发一键开写。

工具清单（Phase 0 目标 12 个）

类别	工具
设备	list_devices、get_device_info
观察	get_screen、get_screen_hash
动作	tap、swipe、scroll_page、type_text、scroll_until、open_app、open_settings、press_key

（verify_element / wait_for / diff_state / smart_scroll 属阶段 1）

WiFi adb 注意事项与重连流程

• 调试设备通过 WiFi adb 连接时，请勿在测试中切换 Wi-Fi 开关——关闭瞬间手机会断网，adb 连接随之断开
• IP:端口会随重连变化；灭屏/省电可能导致连接离线

重连流程：

# 1. 确认离线
adb devices                 # 设备消失或显示 offline

# 2. 断开旧连接并重新 connect（手机端需保持"无线调试"开启）
adb disconnect
adb connect <phone-ip>:<port>

# 3. 验证
adb devices                 # 应显示 device（非 offline）
adb -s <serial> shell getprop ro.product.model   # 输出模型号即正常

• 若 connect 后反复 offline：检查手机无线调试端口是否变化、与电脑是否同网段、防火墙是否放行 5555 段端口
• 设备池在每次工具调用前做 health check，连接失效时返回结构化错误，不会卡死调用

验收用例（Phase 0 三用例，均为网络无关操作）

用例	操作链	断言
① 关于手机	open_settings(panel="about_phone") → get_screen	读到设备信息元素（手机名称/存储空间/运行内存/电池）
② 打开 App	open_app("设置")	screen_changed=true，首页出现搜索框等关键元素
③ 表单填写	定位输入框 → type_text → press_key("enter") → get_screen	搜索结果出现（如输入 wifi 出现 WLAN 相关项）
验收用例固化为 tests/test_integration.py，通过 MCP Client 边界端到端执行（ANDROID_TEST_DEVICE=<serial> 时启用）。

开发与测试

.venv/bin/pytest                                    # 单测（无设备，集成用例自动跳过）
.venv/bin/pytest tests/test_integration.py -v       # 三验收用例（需设备）
ANDROID_TEST_DEVICE=192.168.1.15:39455 .venv/bin/pytest   # 全量含真机探针

路线图

• 阶段 0 MVP：FastMCP + uiautomator2 + 语义 tap/scroll_until + 屏幕哈希 + 动作后校验 ← 当前
• 阶段 1：OCR 通道 + Flutter/Unity 兜底 + 多设备池 + wait_for/verify
• 阶段 2：VLM 视觉融合(SoM) + 执行预算 + 端侧 companion 免电脑