MCP 服务已内置于 AYA 桌面端

让 AI 直接操控你的 Android 设备

AYA 内置一个只监听 127.0.0.1 的 MCP（Model Context Protocol）服务，把手机能力封装成 72 个 aya_* 工具。在 CodeBuddy、WorkBuddy、Claude 里说一句"打开设置，把字体调到最大并截图"，剩下的交给 AI —— 不用再写脚本、跑命令、粘输出。

3 步接入 MCP 查看 72 个工具了解原版 AYA

72MCP 工具（28 只读 / 44 写）

< 1 min从开启到 AI 接管设备

127.0.0.1仅本机监听，不出网

Win / mac / Linux跨平台 Electron 桌面端

Model Context Protocol

MCP 是什么？为什么手机需要它

MCP 是 AI 客户端与工具之间的开放协议。过去 AI 只能"教你怎么操作手机"，现在它能自己调工具、看结果、再决定下一步。 AYA MCP 就是把 adb 的几十年积累，翻译成 AI 听得懂、调得动的 72 个标准工具。

会说人话就够了

不用记 adb shell am start -n ...。自然语言描述目标，AI 自己选择并组合工具，失败还会根据返回的错误自我纠正。

看得见界面，不只是命令

aya_ui_dump 返回带坐标与索引的 UI 层级树，aya_screencap 回传截图。AI 既读结构也看画面，点得准、判得对。

一次调用干完一串动作

aya_batch 串行执行最多 20 个动作，中间不经过模型思考，彻底避开播放器控制栏、Toast 这类 1–3 秒就消失的控件。

关于二次开发：本分支基于开源项目 AYA（ liriliri/aya，作者 surunzi，AGPL-3.0）二次开发，完整保留原版投屏、文件管理、日志、性能、Shell 等桌面能力，仅新增 MCP 服务层：设置 → MCP → 启用即可，不影响原有使用习惯。

Tool Reference

72 个工具，11 个分类

工具名统一以 aya_ 开头：28 个只读默认开放，44 个写需勾选「允许写操作」。这里只列最常用的 12 个，完整 72 个（按分类、可搜索、可只看只读/写）在完整工具清单页面。

上手最常用的 12 个 12 / 72

工具	权限	说明
`aya_list_devices`	只读	列出已连接设备并标注 AYA 当前选中设备，调用其它工具前先确认 deviceId。
`aya_screencap`	只读	截图并直接返回图片，默认缩放到 900px 宽、JPEG 质量 72。
`aya_ui_dump`	只读	UI 层级树，节点含 bounds / center，支持过滤、分页与快照复用。
`aya_tap`	写	坐标、nodeIndex+snapshotId 或 text·id·desc 定位点击，默认点完立即回传新界面。
`aya_batch`	写	一次串行执行最多 20 个动作，专治 1–3 秒消失的播放器控制栏与 Toast。
`aya_wait_for`	只读	轮询等待控件出现或消失，命中即返回，比反复 dump 省往返。
`aya_start_app`	写	启动 Launcher Activity，可等到前台切换或指定控件出现。
`aya_logcat`	只读	日志快照，级别 / 标签 / 关键字过滤在设备端完成，附崩溃摘要。
`aya_shell`	写	adb shell，30s 超时，输出截断 20000 字符，兜底所有未封装的能力。
`aya_serial_logs`	只读	按来源、关键字或正则、fromSeq 增量读取串口日志。
`aya_webview_eval`	写	在 WebView 页面里执行 JavaScript 并返回值，H5 调试比截图快 1–2 个数量级。
`aya_pull_file`	写	把设备文件拉回本机，省略目标路径时存到临时目录 `aya-mcp/`。

设备与屏幕 5

list_devices、device_info、screencap、ui_dump、current_app —— 先认设备，再截图或取 UI 树。

交互 9

tap、tap_text、swipe、long_press、gesture、key、text、batch、wait_for —— 点、滑、按、输一步到位。

日志与命令 4

logcat 快照与等待、清空缓冲区、adb shell，崩溃与 ANR 排查的主力。

串口 11

列串口、开关、读写、暂停恢复、阶段切分与等待关键字，覆盖 bootloader 到 Android 启动全程。

性能与统计 3

CPU / 内存 / 帧率快照、进程列表，以及每个工具的耗时与 dump 复用率。

端口映射 3

adb forward / reverse 的列出、新增与移除，调试设备内 HTTP 服务与 WebView。

WebView 调试 9

列页面、执行 JS、console、网络、元素快照、等待、点击、输入、导航，H5 问题直读 DOM。

录屏与投屏 5

开录、停录并拉回 mp4、查询录制状态，以及投屏窗口与画质控制。

查看全部 72 个工具只看 28 个只读工具

点击定位小贴士：aya_ui_dump 返回的 i 是未过滤完整树的 DFS 前序号，过滤只减少返回节点、不改变 i。snapshotId 60s 过期，任何输入类工具执行后立即失效，返回 STALE_SNAPSHOT 时重新 dump 即可。

Enable MCP

打开 MCP 服务：入口就在设置里

MCP 服务由 AYA 桌面端托管，没有命令行、没有额外进程。按下面四步点开并勾选「启用 MCP 服务」就算打开了；关掉这个开关，AYA 就回到原版状态。

打开「设置」 点主界面右上角的齿轮图标，或走菜单 工具 → 设置。
切到 MCP 分组 弹窗左侧只有「外观 / ADB / MCP」三项，点最下面的 MCP。
勾选「启用 MCP 服务」 勾上后服务立即在本机启动，默认端口 7788，并自动生成访问令牌。
按需放开能力 需要点击、输入、shell 就勾「允许写操作」；要跨设备连接再勾「允许局域网访问」。

AYA 设置 → MCP 面板：勾选启用 MCP 服务、允许写操作、允许局域网访问，端口 7788，状态显示 http://198.18.0.1:7788/mcp 运行中 · 72 个工具 — **设置 → MCP**：三项开关 + 端口 + 实时状态。图中已勾选局域网访问，所以地址显示为 `http://198.18.0.1:7788/mcp`；只用本机时这里是 `127.0.0.1`。行末的「72 个工具」是当前版本实际暴露的数量，会随版本与写操作开关变化。

面板上每一项管什么跟着截图看

控件	默认	作用
`启用 MCP 服务`	打开	总开关。开启即监听本机端口并提供 `aya_*` 工具；首次开启会自动弹出配置片段弹窗。
`允许写操作`	按需	暴露点击、滑动、输入、按键、shell、安装卸载等写工具。不勾时客户端只能读屏、抓日志、传文件。
`允许局域网访问`	关闭	勾选后监听地址从 `127.0.0.1` 变为 `0.0.0.0`，同网段的其它机器可按状态行给出的 IP 连接。
`端口`	`7788`	取值范围 1024–65535。被占用时改一个数字，地址会随之更新。
状态行	—	绿点即「运行中」，后面依次是完整端点地址与当前暴露的工具数量，改开关后会实时刷新。
`查看 MCP 配置`	—	弹出 stdio（推荐）/ stdio（无 env）/ HTTP 三种片段，令牌已填好，点「复制」即可粘到客户端。
`重置访问令牌`	—	令牌泄露或换机器时点它，旧令牌立即失效，记得同步更新客户端配置。

路径速记：工具栏齿轮（或菜单 工具 → 设置）→ 左侧 MCP → 勾选 启用 MCP 服务 → 点 查看 MCP 配置 复制片段。状态行显示的工具数会随「允许写操作」变化，客户端没刷新时重连一次即可。

Quick Start

三步，把手机交给 AI

无需 Root，手机上也无需安装任何 App。只要开启 USB 调试 / 无线调试，电脑上跑着 AYA 就行。

开启 MCP 服务

设置 → MCP → 勾选「启用 MCP 服务」。服务随应用启动自动拉起，默认端口 7788，同时生成访问令牌。需要点击、安装、shell 等能力时，再勾选「允许写入操作」。具体入口与面板截图见上一节。

复制配置片段

弹窗里直接给出三种写好的配置：stdio（推荐）、stdio（无 env）、HTTP。点「复制」，片段里已带好端口与令牌。

粘贴到 AI 客户端

CodeBuddy：设置 → MCP → 添加 MCP，粘贴到 ~/.codebuddy/mcp.json。其他支持 MCP 的客户端同理，重连后即可看到 aya_* 工具列表。

// AYA 设置 → MCP → 查看配置，直接复制即可（令牌已填好）
{
  "mcpServers": {
    "aya": {
      "type": "stdio",
      "command": "C:/Path/To/AYA.exe",      // 客户端用 AYA 自带的 node 启动桥接脚本
      "args": [
        "resources/mcp/aya-mcp-stdio.cjs",
        "--url=http://127.0.0.1:7788/mcp",
        "--token=<your-token>"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1",
        "AYA_MCP_URL": "http://127.0.0.1:7788/mcp",
        "AYA_MCP_TOKEN": "<your-token>"
      },
      "description": "AYA Android device control"
    }
  }
}

// 客户端找不到 AYA.exe 时，用系统 node 直接跑桥接脚本
{
  "mcpServers": {
    "aya": {
      "type": "stdio",
      "command": "node",
      "args": [
        "resources/mcp/aya-mcp-stdio.cjs",
        "--url=http://127.0.0.1:7788/mcp",
        "--token=<your-token>"
      ],
      "description": "AYA Android device control (no env fallback)"
    }
  }
}

// HTTP 无状态：切换写权限后需重新 tools/list（或重连）
{
  "mcpServers": {
    "aya": {
      "type": "http",
      "url": "http://127.0.0.1:7788/mcp",
      "headers": { "Authorization": "Bearer <your-token>" },
      "description": "AYA Android device control"
    }
  }
}

桥接脚本通过 SSE 收到 notifications/tools/list_changed 后会通知客户端热刷新；客户端不支持热更新时重连一次即可。端口被占用可在设置里改（1024–65535），令牌泄露可点「重置访问令牌」。

Use Cases

AI 能替你干这些活

下面每条都是真实可跑的工具组合，把「写脚本 → 运行 → 解析输出」的往返压缩成一句话。

自动化回归与冒烟

"装上新构建，依次走完登录 → 下单 → 支付，每步截图，失败就把 logcat 的 E 级日志带回来。"——aya_install_app → aya_batch → aya_screencap → aya_logcat。

UI 走查与适配检查

"把字体缩放到 2.0，逐个页面截图，列出文字被截断的控件。"——aya_set_font_scale + aya_ui_dump + aya_screencap。

崩溃与 ANR 排查

"清一下日志，复现这个操作，把 E 级日志和 /sdcard 下的 tombstone 拉回本机。"——aya_clear_logcat → 操作 → aya_logcat{level:'E'} → aya_pull_file。

复现视频与缺陷留证

"开始录屏，执行刚才那串操作，停录，把 mp4 存到桌面。"——开录 → aya_batch → aya_stop_recording，全程不碰鼠标。

性能体检

"滚动首页 30 秒，采样帧率和内存，告诉我掉帧的时段。"——aya_performance + aya_swipe + aya_list_processes。

H5 / 混合应用调试

"列出前台应用的 WebView，把 devtools 调试地址给我。"——aya_list_webviews 自动 adb forward 并访问 /json；配合 aya_add_port 可把手机端口映射到本机。

Security

默认收紧，能力给你、风险留给自己可控

MCP 服务跑在你自己的电脑上，设备数据不出本机；危险能力需要你显式授权。

只监听本机或内网：外部网络无法访问，端口范围 1024–65535，默认 7788。
Bearer Token 鉴权：令牌首次开启时生成并持久化，可随时「重置访问令牌」。
写操作默认隐藏：44 个写工具需勾选「允许写入操作」才暴露，28 个只读工具始终可用。
Origin 校验 + 2MB 请求体限制：防止网页跨站调用与超大 payload 打爆服务。
shell 有兜底：aya_shell 30s 超时、输出截断 20000 字符，破坏性命令仍由客户端按 readOnlyHint 弹确认框。

关于局域网 / 远程访问：MCP 服务默认只监听本机回环地址 127.0.0.1，局域网内其它设备、以及公网都无法直接连上，这是有意的安全设计——设备数据始终留在你的电脑上。如果你确实需要「手机接在 A 机器、AI 客户端跑在 B 机器」这类跨机/远程场景，可以自行用 SSH 隧道、frp、ngrok 等工具把本机的 127.0.0.1:7788 映射出去；但在开放端口前，请务必确认已开启 Bearer Token，并只允许可信网络访问，不要直接把端口暴露到公网。

FAQ

常见问题

AYA MCP 和原版 AYA 是什么关系？

本分支基于开源项目 AYA（liriliri/aya，作者 surunzi，AGPL-3.0）二次开发，完整保留原版投屏、文件管理、日志、性能、Shell、应用管理等桌面能力，只新增了 MCP 服务层。关闭 MCP 开关时，它就是原版 AYA。

需要 Root 或在手机上安装 App 吗？

都不需要。AYA 通过 adb 与设备通信，只需在手机上开启 USB 调试（或无线调试）并授权本机调试。

客户端只看到 28 个只读工具怎么办？

说明未勾选「允许写入操作」。勾选后重连 MCP 服务，或等待 tools/list_changed 热刷新，即可看到全部 72 个工具；也可以先在完整工具清单里确认目标工具是只读还是写。

aya_tap 返回 STALE_SNAPSHOT？

UI 快照 60s 过期，且任何输入类工具执行后会立即失效。重新 aya_ui_dump 拿到新的 snapshotId 和 nodeIndex 再点。

点开播放器控制栏后读不到控件？

这类控件只停留 1–3 秒。用 aya_tap 默认的 withUi（点完立刻抓一帧）、或把「点击 → 等待 → 再点击」合成一次 aya_batch，就能避开模型思考延迟。

MCP 开关打不开，提示端口被占用？

默认 7788 被其他进程占了。在设置里换一个 1024–65535 的端口重试，设置项会直接显示错误原因。

支持哪些 AI 客户端？

任何支持 MCP 的客户端都可以，包括 CodeBuddy、WorkBuddy、Claude Desktop、Cursor、Cline 等。配置片段在 AYA 设置里一键复制。

MCP 支持局域网或远程访问吗？

默认不支持。服务只监听 127.0.0.1（本机回环），局域网内其它设备和公网都连不上，设备数据不出本机。这是默认的安全设定。若有跨机需求（例如手机接在一台机器、AI 客户端在另一台），可用 SSH 隧道、frp、ngrok 等把本机 127.0.0.1:7788 端口转发出去；开放前请务必开启 Bearer Token，并只暴露给可信网络，切勿直接面向公网。

What's New

版本	改动
`v2.1.2`	修复安装版「检查更新」报错：更新检查改为直接读取 GitHub Releases API，不再依赖 Release 里的 `latest.yml`；按版本号挑选最新正式版，忽略 `x.y.z.Test` 这类测试 tag。工具总数扩展到 72 个（新增 `aya_gesture`、`aya_long_press`、`aya_webview_*` 系列、屏幕适配与 `aya_stats`）。
`v2.1.0`	新增串口调试面板（bootloader / kernel / android 分段识别、关键字与阶段过滤、暂停、保存会话、波特率自动探测）与 8 个 `aya_serial_*` 工具，工具总数 50；发送框不再记录历史输入；版本号独立于上游，改为 `2.1.0`。
`v1.14.3+mcp`	同步上游至 AYA v1.14.3；Windows 下关闭主窗口改为最小化到系统托盘（托盘右键菜单退出）；更新检查接入 GitHub Releases；优化一键编译脚本与资源准备流程。
`v1.14.2+mcp`	首个 MCP 分支：内置只监听 `127.0.0.1` 的 MCP 服务，暴露 42 个 `aya_*` 工具（16 只读 / 26 写），支持 stdio 与 HTTP 两种接入方式。

现在就让 AI 帮你操作手机

下载 AYA（含 MCP 分支），设置 → MCP → 启用，复制配置粘贴进你的 AI 客户端。整个过程不到一分钟。

下载 AYA 查看接入配置