58 个 MCP 工具分类速查表:android-remote-control-mcp 工具清单与调用示例大全

原创2026-10-29 14:49:261,943 阅读

58 个 MCP 工具分类速查表:android-remote-control-mcp 工具清单与调用示例大全

android-remote-control-mcp 是一个运行在手机上的 Android MCP Server,通过 58 个 MCP 工具让 AI 客户端(Claude、Cursor、LangChain 等)远程操控 Android 设备:点击、滑动、输入文字、读写文件、拍照、读取通知,还支持 Cloudflare 与 ngrok 自动隧道。本文提供一份完整的 MCP 工具分类速查表与调用示例,帮你快速定位需要的工具。

一分钟了解工具命名与调用方式

所有工具默认以 android_ 前缀命名。如果你在应用设置中配置了设备标识(device slug),如 pixel7,前缀会自动变为 android_pixel7_,方便同时连接多台手机。

设备标识 工具名示例
(空) android_tap、android_get_screen_state
pixel7 android_pixel7_tap、android_pixel7_get_screen_state

所有通信走单一端点 POST /mcp(Streamable HTTP,JSON-RPC 2.0,仅支持 POST),每个请求都需携带 Bearer Token:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<工具名>",
    "arguments": { }
  }
}

完整协议细节见 MCP_TOOLS.md,架构设计见 ARCHITECTURE.md。

14 大类 58 个 MCP 工具总览

MCP 工具驱动 AI 在手机上搜索航班机票

# 分类 工具数 工具清单
1 屏幕状态 Screen Introspection 1 android_get_screen_state
2 系统操作 System Actions 6 android_press_back、android_press_home、android_press_recents、android_open_notifications、android_open_quick_settings、android_dismiss_keyboard
3 触摸操作 Touch Actions 5 android_tap、android_long_press、android_double_tap、android_swipe、android_scroll
4 手势 Gestures 2 android_pinch、android_custom_gesture
5 节点操作 Node Actions 6 android_find_nodes、android_click_node、android_long_click_node、android_tap_node、android_scroll_to_node、android_scroll_node
6 文本输入 Text Input 5 android_type_append_text、android_type_insert_text、android_type_replace_text、android_type_clear_text、android_press_key
7 实用工具 Utilities 5 android_get_clipboard、android_set_clipboard、android_wait_for_node、android_wait_for_idle、android_get_node_details
8 文件操作 File Operations 8 android_list_storage_locations、android_list_files、android_read_file、android_write_file、android_append_file、android_file_replace、android_download_from_url、android_delete_file
9 应用管理 App Management 3 android_open_app、android_list_apps、android_close_app
10 相机 Camera 6 android_list_cameras、android_list_camera_photo_resolutions、android_list_camera_video_resolutions、android_take_camera_photo、android_save_camera_photo、android_save_camera_video
11 意图 Intent 2 android_send_intent、android_open_uri
12 通知 Notification 6 android_notification_list、android_notification_open、android_notification_dismiss、android_notification_snooze、android_notification_action、android_notification_reply
13 位置 Location 1 android_get_location
14 共享 Sharing 2 android_get_shared_content、android_share_file_via_web

💡 每个工具都可以在应用内的 MCP Tools 权限设置中单独启用/禁用,或按参数粒度细粒度控制。

1. 屏幕状态:android_get_screen_state 一个工具看全屏幕

这是整个项目的核心工具,一次调用返回:屏幕尺寸 + 所有窗口(含系统弹窗、权限框、输入法键盘)的紧凑 TSV 节点列表,可选返回带标注框的低分辨率截图。它替代了早期的 get_accessibility_tree、capture_screenshot 等 4 个工具,大幅节省 token。

常用参数:

参数 说明
include_screenshot 是否附带低分辨率截图(默认 false,仅在节点列表不够用时开启)
annotate 截图上绘制节点边框与 ID(默认 true)
cursor 分页游标,用于长列表翻页
include_offscreen 是否列出屏幕外节点(默认 true)
include_hierarchy 是否包含节点层级缩进(默认 true)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "android_get_screen_state",
    "arguments": { "include_screenshot": true }
  }
}

源码:ScreenIntrospectionTools.kt

2. 系统操作:6 个按钮级工具

无需坐标,直接模拟系统手势:

  • android_press_back / android_press_home / android_press_recents:返回、回到桌面、查看最近任务
  • android_open_notifications / android_open_quick_settings:展开通知栏、下拉快速设置
  • android_dismiss_keyboard:收起输入法

所有参数均为空对象 {},例如:

{ "name": "android_press_back", "arguments": {} }

3. 触摸操作与手势:坐标驱动基础交互

AI 通过 MCP 工具在手机上自动搜索并预订航班

坐标类工具(x、y 为屏幕像素坐标):

工具 作用 关键参数
android_tap 单击 x、y
android_long_press 长按 x、y、duration
android_double_tap 双击 x、y
android_swipe 从一点滑向另一点 start_x、start_y、end_x、end_y
android_scroll 在区域内滚动 x、y、direction、distance

手势进阶:

  • android_pinch:双指缩放(放大/缩小地图、图片)
  • android_custom_gesture:多段点序列,绘制任意自定义手势轨迹

示例——点击屏幕 (500, 1000):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "android_tap",
    "arguments": { "x": 500, "y": 1000 }
  }
}

4. 节点操作:按语义定位元素,告别盲猜坐标

AI 通过 MCP 工具自动安装并预订机票应用

节点类工具通过 node_id 精准操作元素,配合 android_find_nodes 先定位:

工具 作用
android_find_nodes 按 text / content_desc / resource_id / class_name 查找节点,返回 node_id 列表
android_tap_node / android_click_node 点击节点(tap_node 推荐用于可点击元素)
android_long_click_node 长按节点
android_scroll_to_node 自动滚动直到目标节点出现在屏幕上
android_scroll_node 滚动列表型节点本身

查找示例——精确匹配文本为 "提交" 的按钮:

{
  "name": "android_find_nodes",
  "arguments": { "by": "text", "value": "提交", "exact_match": true, "visible_only": true }
}

💡 推荐工作流:android_get_screen_state 看全局 → android_find_nodes 精确定位 → android_tap_node 执行点击。

源码:NodeActionTools.kt、NodeTargetResolver.kt

5. 文本输入:5 个工具覆盖输入框所有场景

工具 作用
android_type_append_text 在光标处追加文本(最常用)
android_type_insert_text 在指定节点插入文本
android_type_replace_text 替换输入框已有内容
android_type_clear_text 清空输入框
android_press_key 发送按键事件(Enter、Tab、Delete 等)

底层采用自适应节流的自然输入(verified typing),兼容各类 App 的输入监听机制,详见 TextInputTools.kt 与 TypeInputController.kt。

6. 实用工具:剪贴板与等待

工具 作用
android_get_clipboard / android_set_clipboard 读取 / 写入剪贴板文本(无障碍服务豁免 Android 10+ 后台限制)
android_wait_for_node 轮询等待某个节点出现/消失,省去盲目 sleep
android_wait_for_idle 基于屏幕指纹相似度判断页面稳定(如加载完成、动画结束)
android_get_node_details 获取节点完整属性(文本、可点击性、边界等)

7. 文件操作:8 个工具管理手机存储

文件操作基于用户授权存储位置(Storage Location),可添加任意目录或内置的 MediaStore、DCIM、Recordings 等位置:

工具 作用
android_list_storage_locations 列出可用存储位置及 location_id
android_list_files 列出目录内容
android_read_file 读取文件内容
android_write_file / android_append_file 写入 / 追加文件
android_file_replace 文件内查找替换
android_download_from_url 让手机下载 URL 文件(自动拦截内网地址,防止 SSRF)
android_delete_file 删除文件

调用时通常需传 location_id + 相对路径。源码:FileTools.kt、DownloadUrlValidator.kt

8. 应用管理:打开、列出、关闭 App

AI 通过 MCP 工具自动在 Reddit 发帖

工具 作用 关键参数
android_list_apps 列出已安装应用 filter(all/user/system)、name_query
android_open_app 按包名启动应用 package_id,如 com.android.calculator2
android_close_app 关闭指定应用 package_id

9. 相机:6 个工具拍照录像

工具 作用
android_list_cameras 列出摄像头及 ID
android_list_camera_photo_resolutions / android_list_camera_video_resolutions 查询支持分辨率
android_take_camera_photo 拍照并直接返回 JPEG(base64),默认 720p,上限 1920x1080,支持 quality、flash_mode
android_save_camera_photo 拍照并保存到高清晰度文件
android_save_camera_video 录制视频并保存
{
  "name": "android_take_camera_photo",
  "arguments": { "camera_id": "0", "quality": 90, "flash_mode": "off" }
}

10. 意图与 URI:跨 App 跳转

  • android_send_intent:发送自定义 Android Intent(指定 action、category、component、extras 等),可打开其他 App 的任意入口
  • android_open_uri:打开 content://、tel:、https:// 等 URI,最简单直接的跳转方式

11. 通知:6 个工具全自动化处理消息

工具 作用
android_notification_list 列出活跃通知(含标题、正文、操作按钮及 notification_id/action_id),可按 package_name 过滤
android_notification_open 点开通知触发其内容
android_notification_dismiss 划掉通知
android_notification_snooze 挂起/延后通知
android_notification_action 点击通知上的操作按钮(如"已读")
android_notification_reply 直接在通知上回复消息
{
  "name": "android_notification_list",
  "arguments": { "limit": 10 }
}

12. 位置与共享:2 个高价值工具

  • android_get_location:返回经纬度、精度半径(米)和逆地理编码出的街道地址;fresh_fix: true 强制重新定位(最多等 10 秒)
  • android_get_shared_content:读取系统"分享"面板共享到本应用的内容(文本/图片/文件),一次性读空收件箱
  • android_share_file_via_web:把设备文件生成为1 小时有效的一次性下载 URL

调用示例与错误处理

一个完整的 curl 调用示例(查询设备位置):

curl -X POST http://192.168.1.5:8080/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": { "name": "android_get_location", "arguments": { "fresh_fix": true } }
  }'

响应统一为 content 数组:文本用 {"type":"text","text":"..."},图片用 {"type":"image","data":"<base64>","mimeType":"image/jpeg"}。

错误处理要点:

  • 工具级错误不返回 JSON-RPC error code,而是 isError: true + 文本消息(如 Accessibility service not enabled)
  • 客户端可发送 notifications/cancelled 取消正在执行的工具调用
  • 返回设备内容的工具(屏幕、文件、剪贴板、通知等)会附带反提示注入警告头,提醒 LLM 将内容视为不可信输入

快速上手建议

  1. 首次使用先调 android_list_apps + android_open_app 打开目标应用
  2. 用 android_get_screen_state 了解界面,默认不请求截图以省 token
  3. 定位元素优先 android_find_nodes + android_tap_node,坐标点击作为兜底
  4. 页面加载等待用 android_wait_for_node / android_wait_for_idle,不要用 sleep
  5. 涉及敏感操作前,确认 Bearer Token 认证已开启,并按需关闭不需要的工具权限

各工具的完整参数 Schema 与响应示例,请查阅官方工具参考文档 MCP_TOOLS.md 与 PERMISSIONS.md。

登录后查看全文
android-remote-control-mcp