AI导哈

Android多设备自动化服务

MCP Android Server是一个基于Python的多设备Android自动化服务器，支持通过多种传输方式（stdio、HTTP、SSE）暴露Android自动化能力，适用于多设备并行测试和UI交互场景。

  • by smutti
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 smutti/mcp_android

使用说明

MCP安卓服务器

用于Android自动化的多设备MCP服务器，内置Python adbutils 和 uiautomator2.

它做什么

  • 将Android自动化功能作为MCP工具公开。
  • 支持并行连接多个设备。
  • 使用每个设备的会话缓存和UI锁来避免在同一设备上发生冲突的操作。
  • 使用 stdio, streamable-http，以及 sse 运输。

技术栈

  • python >=3.11
  • uv 用于依赖性和环境管理
  • mcp （快速MCP）
  • adbutils
  • uiautomator2
  • Pillow

先决条件

  • adb 已安装并可用 PATH
  • 一个或多个已连接并授权的Android设备/模拟器(adb devices)
  • uv 安装

安装

uv sync

如果您使用现有的虚拟环境：

source .venv/bin/activate
uv sync

运行服务器

标准输入输出传输

uv run mcp-android-server --mode stdio

可流式HTTP传输

uv run mcp-android-server --mode streamable-http --port 3001

MCP端点URL:

http://127.0.0.1:3001/mcp

SSE运输

uv run mcp-android-server --mode sse --port 3001

CLI选项

--mode {stdio,streamable-http,sse}
--port PORT
--default-serial SERIAL
--max-workers N
--session-ttl-s SECONDS
--healthcheck-interval-s SECONDS
--connect-retries N
--connect-backoff-s SECONDS

环境变量（相当于CLI默认值）：

  • MCP_TRANSPORT
  • MCP_PORT
  • MCP_DEFAULT_SERIAL
  • MCP_MAX_WORKERS
  • MCP_SESSION_TTL_S
  • MCP_HEALTHCHECK_INTERVAL_S
  • MCP_CONNECT_RETRIES
  • MCP_CONNECT_BACKOFF_S

MCP客户端配置

基于HTTP的编解码器API

将此添加到 ~/.codex/config.toml:

[mcp_servers.android]
url = "http://127.0.0.1:3001/mcp"

Codex通过本地STDIO命令

[mcp_servers.android]
command = "uv"
args = ["run", "mcp-android-server", "--mode", "stdio"]
cwd = "/absolute/path/to/mcp_android"

[mcp_servers.android.env]
PYTHONPATH = "src"

刀具目录

所有设备专用工具均可接受 serial. 如果 serial 省略，解析顺序为：

  1. --default-serial / MCP_DEFAULT_SERIAL
  2. 唯一连接的设备
  3. 连接多个设备时出错

设备工具

  • list_devices()
  • get_device_status(serial)
  • clear_device_session(serial)
  • list_active_sessions()

日志记录

  • get_logcat_output(serial?, app_package, log_level="DEBUG", max_lines=100)

log_level 值：

  • DEBUG
  • INFO
  • WARNING
  • ERROR

屏幕和UI检查

  • get_screenshot(serial?, scale_factor=0.4)
  • get_ui_dump(serial?, returned_attributes)

允许 returned_attributes 值：

  • index, text, resource-id, class, package, content-desc
  • checkable, checked, clickable, enabled, focusable, focused
  • scrollable, long-clickable, password, selected, bounds
  • drawing-order, hint

UI交互

  • click_ui_element(serial?, text?, resource_id?, content_desc?, timeout_s=10.0)

对于 click_ui_element，在以下选项中只提供一个选择器：

  • text
  • resource_id
  • content_desc

输入和系统动作

  • tap_screen(serial?, x, y)
  • swipe_screen(serial?, x1, y1, x2, y2, duration_ms=300)
  • send_text(serial?, text_to_send, clear_existing=false)
  • perform_system_action(serial?, action) 哪里 action 是：
    • BACK
    • HOME
    • RECENT_APPS

示例流程

  1. 呼叫 list_devices.
  2. 呼叫 get_screenshot 检查当前状态。
  3. 呼叫 get_ui_dump 查找选择器。
  4. 呼叫 click_ui_element 或 tap_screen.
  5. 呼叫 get_logcat_output 用于应用程序诊断。

测试

运行单元测试：

uv run python -m unittest discover -s tests/unit -v

故障排除

  • Device not found:
    • 检查序列号 list_devices.
  • Multiple devices connected. Please specify serial:
    • 通过 serial 显式或设置 --default-serial.
  • 找不到UI元素：
    • 使用 get_ui_dump 并验证确切的选择器文本/资源id/内容描述。
  • 没有返回的日志 get_logcat_output:
    • 确保应用程序进程正在运行 app_package 是正确的。
  • 亚行授权问题：
    • 重新连接设备并接受RSA授权提示。

相关 MCP