使用说明
aiphone mcp
MCP服务器，用于通过ADB控制Android设备。展示用于屏幕截图、UI交互、应用程序管理、无线ADB和设备诊断的工具。
适用于任何兼容MCP的客户端：LM Studio、Claude Desktop、Cursor、Windsurf。
特性
- 自动压缩的屏幕截图（WebP、JPEG、PNG）
- UI检查——点击、滑动、键入、按选择器查找元素
- 应用程序控制——启动、停止、安装检查、打开URL
- 基于TCP/IP的无线ADB
- 设备信息——电池、内存、存储、网络接口
- 导航——主页、后退、最近、屏幕旋转
- 通知——发布和检查系统通知
- 连接性——切换WiFi、移动数据、飞行模式
- 断言——前台应用程序和元素存在性检查
- 逃生舱——任意运行
adb shell命令
需求
- Node.js 18+
- 安卓调试桥 在你的路径中
- 启用USB调试的Android 8+
要启用USB调试：设置→ 关于手机→ 点击“内部版本号”7次→ 开发人员选项→ USB调试。
安装
npx （无需安装）：
npx aiphone-mcp
全局安装:
npm install -g aiphone-mcp
本地克隆:
git clone <repository-url>
cd aiphone-mcp
npm install
npm link
客户端配置
所有客户端都使用相同的配置结构。入口点是 npx aiphone-mcp.
{
"aiphone": {
"command": "npx",
"args": ["aiphone-mcp"]
}
}
配置
| 变量 | 默认值 | 描述 |
|---|---|---|
AIPHONE_ADB_PATH |
adb |
adb二进制文件的路径 |
{
"aiphone": {
"command": "npx",
"args": ["aiphone-mcp"],
"env": {
"AIPHONE_ADB_PATH": "/usr/local/bin/adb",
}
}
}
可用工具
设备
| 工具 | 说明 |
|---|---|
list_devices |
列出所有连接的ADB设备序列 |
get_device_info |
完整的硬件标识、电池、内存、存储和网络信息 |
get_screen_size |
物理屏幕分辨率（像素） |
get_foreground_app |
用户当前可见的包和窗口 |
屏幕观察
| 工具 | 说明 |
|---|---|
take_screenshot |
将屏幕捕获为优化图像（默认为WebP）。支持 max_width, max_height, format，以及 quality 参数。 |
get_ui_elements |
从UIAutomator层次结构解析交互式UI元素列表 |
dump_ui_xml |
原始UIAutomator XML层次结构字符串 |
交互
| 工具 | 说明 |
|---|---|
tap |
点击屏幕绝对坐标 |
double_tap |
双击绝对屏幕坐标 |
tap_element |
按边界数组点击元素的中心 [x1, y1, x2, y2] |
tap_by_selector |
通过选择器找到一个元素并点击它 |
swipe |
滑动手势——定向(up, down, left, right)或基于坐标 |
type_text |
在当前聚焦的输入字段中键入文本 |
type_in_element |
按选择器查找输入字段，将其聚焦，清除现有文本，然后键入 |
press_key |
按名称按键(back, home, enter, search, delete, ...）或数字键码 |
元素选择器
| 工具 | 说明 |
|---|---|
find_element |
通过以下方式查找元素 resourceId, text, contentDesc，或 className |
wait_for_element |
轮询，直到出现匹配的元素或超时为止 |
assert_element_exists |
断言存在与选择器匹配的元素--返回PASS/FAIL |
导航
| 工具 | 说明 |
|---|---|
go_home |
按下主页按钮 |
go_back |
按下后退按钮 |
open_recents |
打开最近使用的应用程序切换器 |
rotate_screen |
设置设备旋转：0=纵向，1=横向，2=反向纵向，3=反向横向 |
delay |
等待指定的毫秒数（最大10 000） |
应用程序控制
| 工具 | 说明 |
|---|---|
open_app |
使用启动意图按包名启动应用程序 |
open_url |
在设备默认浏览器中打开URL |
force_stop_app |
按程序包名称强制停止应用程序 |
is_app_installed |
检查设备上是否安装了软件包 |
list_installed_apps |
返回所有已安装的软件包名称 |
assert_foreground_app |
断言某个包当前位于前台--返回PASS/FAIL |
无线ADB
| 工具 | 说明 |
|---|---|
enable_wireless_adb |
将USB连接的设备切换到TCP/IP模式（在断开USB之前运行） |
get_device_ip |
返回所有具有IP地址的活动网络接口 |
adb_connect |
通过TCP/IP在给定的IP和端口连接到设备 |
adb_disconnect |
断开无线ADB目标的连接，如果没有指定目标，则断开所有无线设备的连接 |
通知
| 工具 | 说明 |
|---|---|
post_notification |
发布系统通知(bigtext, inbox，或 media 风格） |
dump_notifications |
返回原始 dumpsys notification 输出-活动通知和历史记录 |
连接性
| 工具 | 说明 |
|---|---|
set_wifi |
启用或禁用WiFi |
set_mobile_data |
启用或禁用移动数据 |
set_airplane_mode |
启用或禁用飞行模式 |
逃生舱口
| 工具 | 说明 |
|---|---|
adb_shell |
任意运行 adb shell command——当没有其他工具覆盖该操作时使用 |
屏幕截图参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
max_width |
integer | 1080 | 最大宽度（像素）（按比例缩小） |
max_height |
整数 | 1920 | 最大高度（像素）（按比例缩小） |
format |
字符串 | webp |
webp, jpeg，或 png |
quality |
integer | 75 | 压缩质量1–100（PNG忽略） |
图像永远不会被放大。
选择器
定位元素的工具接受 selector 具有以下字段的对象：
| 字段 | 匹配 | 示例 |
|---|---|---|
resourceId |
精确 | "com.example.app:id/search_bar" |
text |
变电站 | "Sign in" |
contentDesc |
变电站 | "Close button" |
className |
精确 | "android.widget.EditText" |
clickableOnly |
过滤器 | true |
优先： resourceId > text > contentDesc > className.
故障排除
未找到设备 --检查USB调试是否已启用，设备是否已授权。跑 adb devices 以验证。
找不到adb --确保 adb 在您的路径中，或已设置 AIPHONE_ADB_PATH 到完整的二进制路径。
无线连接失败 --两台机器必须位于同一网络上。运行 enable_wireless_adb 当USB仍然连接时，使用以下命令获取IP get_device_ip，然后致电 adb_connect.
屏幕截图太大 --使用 max_width: 720, format: "webp" 以减小输出尺寸。
许可证
MIT。看 许可证 全文。
