58 个 MCP 工具分类速查表:android-remote-control-mcp 工具清单与调用示例大全
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 工具总览
| # | 分类 | 工具数 | 工具清单 |
|---|---|---|---|
| 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. 触摸操作与手势:坐标驱动基础交互
坐标类工具(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. 节点操作:按语义定位元素,告别盲猜坐标
节点类工具通过 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
| 工具 | 作用 | 关键参数 |
|---|---|---|
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 将内容视为不可信输入
快速上手建议
- 首次使用先调
android_list_apps+android_open_app打开目标应用 - 用
android_get_screen_state了解界面,默认不请求截图以省 token - 定位元素优先
android_find_nodes+android_tap_node,坐标点击作为兜底 - 页面加载等待用
android_wait_for_node/android_wait_for_idle,不要用 sleep - 涉及敏感操作前,确认 Bearer Token 认证已开启,并按需关闭不需要的工具权限
各工具的完整参数 Schema 与响应示例,请查阅官方工具参考文档 MCP_TOOLS.md 与 PERMISSIONS.md。


