Android MCP

Android MCP Server

一个轻量级 MCP（Model Context Protocol）服务，用于自动化 Android 操作系统。此服务提供与 Android 设备直接交互的工具，可用于自动化测试、应用交互和设备控制。

功能

• 设备控制：在 Android 设备上点击、长按、滑动、拖动和输入文字
• 状态管理：获取设备状态，并可选择获取视觉截图
• 导航：按下硬件按钮并访问通知
• 自动化：提供等待功能以控制时序
• 模拟器支持：同时支持实体设备和 Android 模拟器

前置条件

• Python 3.13 或更高版本
• uv 包管理器
• 已启用 USB 调试的 Android 设备或模拟器
• 已安装且可访问的 ADB（Android Debug Bridge）

安装

1. 安装 uv（如尚未安装）

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: using pip
pip install uv

2. 设置项目

# Navigate to the android MCP directory
cd mcp/android

# Install dependencies
uv sync

# Activate the virtual environment (optional, uv run handles this automatically)
source .venv/bin/activate

3. 验证安装

# Test the server
uv run main.py --help

使用方法

运行服务

对于实体设备：

uv run main.py

对于 Android 模拟器：

uv run main.py --emulator

设备设置

1. 启用 Android 设备上的开发者选项：

   • 前往“设置”>“关于手机”
   • 连续点按“版本号” 7 次

2. 启用 USB 调试：

   • 前往“设置”>“开发者选项”
   • 启用“USB 调试”

3. 连接设备并验证 ADB 连接：

   adb devices
   

MCP 服务配置

将以下配置添加到 MCP 客户端设置中（例如 Claude Desktop、Cline 等）：

{
  "mcpServers": {
    "android-mcp": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "cd /path/to/agent/mcp/android && source .venv/bin/activate && uv run main.py --emulator"
      ],
      "alwaysAllow": [
        "State-Tool",
        "Click-Tool",
        "Type-Tool",
        "Swipe-Tool"
      ]
    }
  }
}

注意：更新配置中的路径，使其与项目的实际位置一致。

配置选项

• 对于实体设备：从 args 中移除 --emulator 标志
• 指定设备：添加 --device <device_id> 以指定特定设备
• alwaysAllow：预先批准特定工具，以避免反复出现权限提示

可用工具

工具	描述	参数
Click-Tool	点击指定坐标	x: int, y: int
State-Tool	获取设备状态，并可选择获取截图	use_vision: bool = false
Long-Click-Tool	长按指定坐标	x: int, y: int, duration: int
Swipe-Tool	在坐标之间滑动	x1: int, y1: int, x2: int, y2: int
Type-Tool	在指定坐标输入文字	text: str, x: int, y: int, clear: bool = false
Drag-Tool	在坐标之间拖放	x1: int, y1: int, x2: int, y2: int
Press-Tool	按下硬件按钮	button: str
Notification-Tool	访问通知面板	无
Wait-Tool	等待指定时长	duration: int

故障排除

常见问题

1. 未找到设备：

   • 确保已启用 USB 调试
   • 检查 adb devices 的输出
   • 尝试更换 USB 线缆或端口

2. 权限被拒绝：

   • 在设备上允许 USB 调试权限
   • 检查 adb devices 中的设备授权状态

3. 连接超时：

   • 重启 ADB：adb kill-server && adb start-server
   • 重新连接设备

4. Python 版本问题：

   • 确保已安装 Python 3.13+
   • 如有需要，使用 uv python install 3.13

模拟器设置

如果使用 Android 模拟器：

1. 启动 Android 模拟器（通常可通过 emulator-5554 访问）
2. 验证连接：adb connect emulator-5554
3. 运行服务时使用 --emulator 标志

开发

项目结构

mcp/android/
├── README.md
├── pyproject.toml
├── main.py           # MCP server entry point
├── src/
│   ├── mobile/       # Device interaction logic
│   └── tree/         # UI tree parsing and state management
└── .venv/           # Virtual environment

依赖项

• mcp：Model Context Protocol 框架
• uiautomator2：Android 设备自动化
• pillow：用于截图的图像处理
• ipykernel：Jupyter 内核支持