安卓MCP

](https://badge.fury.io/js/the-android-mcp) ![License: MIT](https://opensource.org/licenses/MIT) ![TypeScript](https://typescriptlang.org) ](https://nodejs.org)

在几分钟内构建、发布和验证Android UI更改——使用可以看到和触摸您设备的AI代理。

⚡ 这能实现什么（快速）

即时UI反馈：屏幕截图+UI层次结构在一个流程中
闪电登录：自动填表+提交检测
大规模热装：连接端口，安装APK，并从MCP重新启动应用程序
类人导航：内置点击、滑动、滚动和等待逻辑

视觉概述

flowchart LR
  Dev[Code Changes] --> Agent[AI Agent]
  Agent --> MCP[MCP Server]
  MCP --> Device[Android Device]
  Device --> MCP
  MCP --> Agent
  Agent --> Dev

sequenceDiagram
  participant A as AI Agent
  participant M as MCP Server
  participant D as Android Device
  A->>M: smart_login_fast
  M->>D: UI dump and ADB input
  D-->>M: Updated UI state
  M->>D: Tap submit
  M-->>A: Result (fields found, submit tapped)

Web UI v3（本地50000）

本地网络驾驶舱现在是英语优先，初学者优先，高级控制隐藏在显式切换后面。

网址： http://127.0.0.1:50000
启动命令： the-android-mcp-web-ui --serve --host 127.0.0.1 --port 50000
用户体验方向：简单的语言动作、大型引导卡和更清晰的操作反馈。
结构： Simple Mode 对于日常行为， Expert Area 完全控制。
专家区：大型控制集分为可折叠模块 Expand All Modules / Collapse All Modules.
启动安全：默认情况下禁用计划自动恢复；启用 THE_ANDROID_MCP_RESUME_SCHEDULES_ON_START=1.

截图

桌面：

Web UI v3 desktop overview

Android实时会话（从连接的设备工作流中捕获）：

Web UI v3 android live view

快速入门（复制/粘贴）

npm install -g the-android-mcp
the-android-mcp

{
  "mcpServers": {
    "the-android-mcp": {
      "command": "the-android-mcp"
    }
  }
}

工具亮点

目标	工具
快速登录	`smart_login_fast`, `detect_login_fields`, `adb_keyboard_*`
快速流动	`fast_flow`, `run_flow_plan`, `batch_android_actions`
稳健的等待	`wait_for_`, `wait_for__disappear`, `wait_for_ui_stable`
导航	`tap_`, `swipe_`, `scroll_`, `scroll_until_`
应用程序操作	`install_android_apk`, `start_android_app`, `hot_reload_android_app`
问题报告	`create_github_issue`

性能提示（现实世界）

更喜欢 fast_flow + batch_android_actions 减少亚行往返。
使用 wait_for_ui_stable 以避免过渡期间出现片状敲击。
更喜欢 scroll_until_* 通过手动滚动循环。
对于登录屏幕，请使用 smart_login_fast 启用ADB键盘。
使用 smart_swipe / smart_scroll 配置文件(fast, normal, safe)交易速度与稳定性。

效率手册（用于编码人工智能）

你想用的时候就用这个 最高速度 和 亚行最低往返次数.

1）更喜欢“一通电话”流程

使用 fast_flow 或 run_flow_plan 在中组合轻击、文本、等待和屏幕截图 一个电话.
使用 smart_swipe / smart_scroll 到 滑动+稳定+（可选）屏幕截图 在一次通话中。
使用 swipe_and_screenshot 当你只需要快速滑动+捕捉时。

2）将屏幕截图减少到只需要的内容

使用 take_android_screenshot 随着 throttleMs 以重用上次捕获。
更喜欢 UI转储 (dump_android_ui_hierarchy)用于逻辑，屏幕截图仅用于视觉确认。
对于重复的UI查询，请使用 query_ui 随着 useCache/maxAgeMs.

3）使用ADB键盘快速输入

smart_login_fast 随着 useAdbKeyboard=true 是最快的登录路径。
手动输入： adb_keyboard_input 或 adb_keyboard_input_chars.

4）轻击前务必等待稳定

如果屏幕正在更改，请使用 wait_for_ui_stable 或 smart_swipe / smart_scroll.
避免在导航后立即点击，不要等待；它会导致片状。

5）更喜欢基于选择器的点击而不是坐标

使用 tap_by_text, tap_by_id, tap_by_desc，或 query_ui + tap_by_selector_index.
当不存在稳定的选择器时，坐标是一种回退。

6）使用滚动直到助手

scroll_until_text, scroll_until_id, scroll_until_desc 比手动循环更快、更稳定。

7）立即捕获错误报告

当流程失败时，使用 create_github_issue 带有复制步骤+日志/屏幕截图。

流编排器v1（run_Flow_plan）

run_flow_plan 现在支持断言, 重试，以及 故障挂钩 以保持UI流的弹性。

{
  "steps": [
    { "type": "tap_by_text", "text": "Login" },
    { "type": "assert_text", "text": "Welcome", "timeoutMs": 6000 }
  ],
  "stepRetries": 1,
  "retryDelayMs": 400,
  "onFailSteps": [
    { "type": "press_key_sequence", "keyCodes": ["4", "4"] }
  ]
}

问题报告（GitHub）

这 create_github_issue 该工具使用GitHub CLI(gh).确保您已通过身份验证(gh auth login). 使用 dryRun 验证命令而不会产生问题。

{
  "title": "Login submit button not detected on Pixel 7",
  "body": "Steps: open app -> login screen -> submit not tapped. Logs attached.",
  "labels": ["bug", "login"],
  "dryRun": true
}

示例：在一个流程中快速登录+提交+验证

{
  "steps": [
    { "type": "wait_for_ui_stable", "stableIterations": 2 },
    { "type": "smart_login_fast", "email": "user@example.com", "password": "secret", "useAdbKeyboard": true },
    { "type": "wait_for_activity_change", "timeoutMs": 8000 }
  ],
  "stopOnFailure": true
}

ADB支持的模型上下文协议服务器，允许AI编码代理安装、启动和控制Android应用程序，捕获屏幕截图，并连接热重载端口。专为迭代式UI优化、自动化测试流程和Expo、React Native、Flutter和原生Android项目的动手应用导航而构建。

基于原始项目： infiniV/安卓Ui MCP.

关键词： android mcp服务器、adb自动化、android应用测试、热重载、android ui控制、ai代理android、expo、react native、flutter

特性

实时开发工作流程

使用Expo、React Native、Flutter在应用程序开发过程中实时截图
为AI代理提供UI更改和迭代的即时视觉反馈
与开发服务器和热重载工作流无缝集成
在主动开发期间支持物理设备和模拟器
ADB驱动的应用程序安装、启动、输入控制和端口反向，用于实际测试

AI代理集成

支持Claude Desktop、GitHub Copilot和Gemini CLI的MCP协议
使AI代理能够查看您的应用程序UI并提供上下文建议
非常适合迭代式UI优化和设计反馈循环
用于AI驱动的代码生成和UI改进的视觉上下文

开发者体验

零配置设置，运行开发环境
Docker部署用于团队协作和CI/CD管道
全面的错误处理和有用的开发建议
具有超时管理的安全stdio通信

AI代理配置

此MCP服务器与支持模型上下文协议的AI代理协同工作。配置您的首选代理以启用实时Android UI分析：

尽情探索这个工具吧！

我们现在正在后台积极开发——正如你正在阅读的那样。此时此刻正在进行大量工作，甚至更强大的工具已经在开发中。

这个项目正在快速发展，还有更多的事情要做。 🚧

克劳德代码

# CLI Installation
claude mcp add the-android-mcp -- npx the-android-mcp

# Local Development
claude mcp add the-android-mcp -- node "D:\\projects\\the-android-mcp\\dist\\index.js"

克劳德桌面

增添 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "the-android-mcp": {
      "command": "npx",
      "args": ["the-android-mcp"],
      "timeout": 10000
    }
  }
}

GitHub副本（VS代码）

增添 .vscode/settings.json:

{
  "github.copilot.enable": {
    "*": true
  },
  "mcp.servers": {
    "the-android-mcp": {
      "command": "npx",
      "args": ["the-android-mcp"],
      "timeout": 10000
    }
  }
}

Gemini CLI

# CLI Installation
gemini mcp add the-android-mcp npx the-android-mcp

# Configuration
# Create ~/.gemini/settings.json with:
{
  "mcpServers": {
    "the-android-mcp": {
      "command": "npx",
      "args": ["the-android-mcp"]
    }
  }
}

法典

安装时，软件包会自动将服务器添加到 ~/.codex/config.toml 如果文件存在。要跳过自动设置，请设置 THE_ANDROID_MCP_NO_CODEX_SETUP=1. 要跳过安装时Web UI自动启动，请设置 THE_ANDROID_MCP_NO_WEB_UI_AUTOSTART=1.

默认情况下，启动时Web UI计划自动恢复被禁用，以防止意外的后台设备操作。要在启动时显式恢复活动计划，请设置 THE_ANDROID_MCP_RESUME_SCHEDULES_ON_START=1.

如果需要手动添加，请使用：

[mcp_servers.the-android-mcp]
command = "npx"
args = ["-y", "the-android-mcp"]
timeout = 10000

安装

软件包管理器安装

npm install -g the-android-mcp

启动GUI（全局安装后）：

the-android-mcp-gui

源安装

git clone https://github.com/meinzeug/the-android-mcp
cd the-android-mcp
npm install && npm run build

安装验证

安装后，验证软件包是否可用：

the-android-mcp --version
# For npm installation
npx the-android-mcp --version

可选GUI启动：

the-android-mcp-gui

GUI应用程序（Linux）

轻量级的Electron GUI，通过stdio与MCP服务器通信，并为您提供设备的可视化控制界面。

全局GUI（推荐）

the-android-mcp-gui

这使用与npm包捆绑在一起的GUI，并自动启动MCP服务器。

本地GUI（开发）

# build MCP server first
npm run build

# start the GUI
cd apps/gui
npm install
npm run dev

Linux沙盒说明： 如果发生以下情况，GUI启动器会自动禁用Electron沙盒 chrome-sandbox 配置不正确。要强制沙盒，请设置 THE_ANDROID_MCP_FORCE_SANDBOX=1 并修复Electron安装的权限（对于全局安装，这通常在 $(npm root -g)/the-android-mcp/node_modules/electron/dist/chrome-sandbox).

GUI从以下位置自动启动MCP服务器 dist/index.js 并暴露：

设备列表+选择
截图+点击叠加
应用程序安装/启动/停止
文本输入+按键事件
当前活动、窗口大小、UI层次结构转储

开发工作流程

此MCP服务器通过为AI代理提供对正在运行的应用程序的实时可视化访问，改变了您开发Android UI的方式。以下是典型的工作流程：

启动您的开发环境：启动Expo、React Native Metro、Flutter或Android Studio，并运行您的应用程序
连接MCP服务器：配置您的AI代理（Claude、Copilot、Gemini）以使用此MCP服务器
迭代开发：让你的AI代理分析当前的UI，提出改进建议，或帮助实施更改
实时反馈：AI代理会立即截图以查看代码更改的结果
优化并重复：继续与视觉环境进行对话，以更好地进行UI开发

非常适合：

世博会开发，实时预览和热装
使用Metro bundler进行React Native开发
热重载颤振发展
原生Android开发，可即时运行
UI测试和视觉回归分析
人工智能辅助下的协同设计评审
视觉环境下的可访问性测试
跨平台UI一致性检查

先决条件

组件	版本	安装
Node.js	18.0+	下载
npm	8.0+	包含在Node.js中
ADB	最新	Android SDK平台工具

安卓设备设置

启用开发者选项：设置>关于手机>点击“内部版本号”7次
启用USB调试：设置>开发人员选项>USB调试
验证连接： adb devices

开发环境设置

世博发展

启动您的Expo开发服务器：

npx expo start
# or
npm start

在连接的设备或模拟器上打开您的应用程序
确保您的设备出现在 adb devices
您的AI代理现在可以在开发过程中截图

React原生开发

启动地铁捆绑器：

npx react-native start

在Android上运行：

npx react-native run-android

通过AI分析启用热重新加载以获得即时反馈

Flutter开发

在调试模式下启动Flutter：

flutter run

使用热重载(r)热重启(R)同时获得AI反馈
AI代理可以在每次更改后捕获UI状态

原生Android开发

在Android Studio中打开项目
启用即时运行功能运行应用程序
连接设备或启动模拟器
启用AI代理集成以进行实时UI分析

Docker部署

Docker Compose

cd docker
docker-compose up --build -d

为Docker配置AI平台：

{
  "mcpServers": {
    "the-android-mcp": {
      "command": "docker",
      "args": ["exec", "the-android-mcp", "node", "/app/dist/index.js"],
      "timeout": 15000
    }
  }
}

手动Docker构建

docker build -t the-android-mcp .
docker run -it --rm --privileged -v /dev/bus/usb:/dev/bus/usb the-android-mcp

可用工具

工具	说明	参数
`take_android_screenshot`	捕获设备屏幕截图	`deviceId` （可选）， `throttleMs` （可选）
`list_android_devices`	列出已连接的设备	无
`set_device_alias`	设置设备别名	`alias`, `deviceId` （可选）
`resolve_device_alias`	解析设备别名	`alias`
`list_device_aliases`	列出设备别名	无
`clear_device_alias`	清除设备别名	`alias`
`list_imes`	列出可用的Android IMEs	`deviceId` （可选）
`set_ime`	设置当前Android输入法	`imeId`, `deviceId` （可选）
`enable_ime`	启用Android输入法	`imeId`, `deviceId` （可选）
`adb_keyboard_input`	通过ADB键盘输入法输入文本	`text`, `imeId` （可选）， `setIme` （可选）
`adb_keyboard_clear_text`	通过ADB键盘输入法清除文本	`imeId` （可选）， `setIme` （可选）， `deviceId` （可选）
`adb_keyboard_input_code`	通过ADB键盘输入法发送按键代码	`code`, `imeId` （可选）， `setIme` （可选）， `deviceId` （可选）
`adb_keyboard_editor_action`	通过ADB键盘输入法发送编辑器操作	`code`, `imeId` （可选）， `setIme` （可选）， `deviceId` （可选）
`adb_keyboard_input_chars`	通过ADB键盘发送unicode代码点	`text`, `imeId` （可选）， `setIme` （可选）， `deviceId` （可选）
`set_adb_keyboard_mode`	启用/禁用ADB键盘模式	`enable` （可选）， `imeId` （可选）
`smart_login`	快速自动填充登录屏幕	`email`, `password`, `submitLabels`, `submitFallback` （可选）
`detect_login_fields`	检测登录字段和提交按钮	`submitLabels` （可选）， `deviceId` （可选）
`smart_login_fast`	快速登录（单次转储+批量操作）	`email`, `password`, `useAdbKeyboard`, `submitFallback` （可选）
`find_android_apk`	在项目中查找最新的APK	`projectRoot` （可选）
`install_android_apk`	在设备上安装APK	`apkPath`/`apkUrl` （可选）， `deviceId` （可选）、安装标志， `timeoutMs`
`uninstall_android_app`	按程序包名称卸载应用程序	`packageName`, `deviceId` （可选）， `keepData` （可选）
`start_android_app`	启动应用程序（可选活动）	`packageName`, `activity` （可选）， `deviceId` （可选）
`get_android_current_activity`	获取焦点活动	`deviceId` （可选）
`get_android_window_size`	获取设备窗口大小	`deviceId` （可选）
`list_installed_packages`	列出已安装的包名称	筛选器（可选）， `deviceId` （可选）
`is_app_installed`	检查软件包是否已安装	`packageName`, `deviceId` （可选）
`get_app_version`	获取应用程序版本信息	`packageName`, `deviceId` （可选）
`get_android_property`	读取系统属性	`property`, `deviceId` （可选）
`get_android_properties`	按前缀读取系统属性	`prefix` （可选）， `deviceId` （可选）
`open_url`	通过Android意图打开URL	`url`, `deviceId` （可选）
`paste_clipboard`	粘贴剪贴板内容	`deviceId` （可选）
`dump_android_ui_hierarchy`	转储UI层次结构XML	`deviceId` （可选）， `maxChars`, `useCache`, `maxAgeMs` （可选）
`stop_android_app`	强制停止应用程序	`packageName`, `deviceId` （可选）
`clear_android_app_data`	清除应用程序数据	`packageName`, `deviceId` （可选）
`tap_android_screen`	发送点击事件	`x`, `y`, `deviceId` （可选）
`swipe_android_screen`	发送滑动手势	`startX`, `startY`, `endX`, `endY`, `durationMs` （可选）， `deviceId`
`swipe_and_screenshot`	在一次通话中滑动+截图	`startX`, `startY`, `endX`, `endY`, `postSwipeWaitMs` （可选）
`smart_swipe`	滑动+自动等待+可选截图	`startX`, `startY`, `endX`, `endY`, `profile`, `waitForUiStable`
`input_android_text`	在焦点输入中键入文本	`text`, `deviceId` （可选）
`send_android_keyevent`	发送Android密钥事件	`keyCode`, `deviceId` （可选）
`batch_android_actions`	在一次调用中运行多个输入操作	`actions`, `preActionWaitMs` （可选）， `deviceId` （可选）， `captureBefore`/`captureAfter` （可选）， `timeoutMs`
`pm2_start_hot_mode`	通过PM2启动热模式构建	`projectRoot`/`configPath` （可选）， `appName` （可选）
`pm2_stop_app`	按名称停止PM2应用程序	`appName`
`pm2_list`	列出PM2应用程序	无
`fast_flow`	运行快速UI流（批处理+可选转储）	`actions`/`steps`, `stepRetries`, `screenshotThrottleMs` （可选）
`tap_by_text`	按可见文本点击UI节点	`text`, `matchMode` （可选）， `index` （可选）， `deviceId` （可选）
`tap_by_id`	按资源id点击UI节点	`resourceId`, `index` （可选）， `deviceId` （可选）
`tap_by_desc`	按内容描述点击UI节点	`contentDesc`, `matchMode` （可选）， `index` （可选）， `deviceId` （可选）
`wait_for_text`	通过UI转储轮询等待文本	`text`, `matchMode` （可选）， `timeoutMs`/`intervalMs` （可选）
`wait_for_text_disappear`	等待文本消失	`text`, `matchMode` （可选）， `timeoutMs`/`intervalMs` （可选）
`type_by_id`	按id点击字段并键入文本	`resourceId`, `text`, `matchMode`/`index` （可选）， `deviceId` （可选）
`wait_for_id`	通过UI转储轮询等待资源id	`resourceId`, `matchMode` （可选）， `timeoutMs`/`intervalMs` （可选）
`wait_for_id_disappear`	等待资源id消失	`resourceId`, `matchMode` （可选）， `timeoutMs`/`intervalMs` （可选）
`wait_for_desc`	通过UI转储轮询等待内容描述	`contentDesc`, `matchMode` （可选）， `timeoutMs`/`intervalMs` （可选）
`wait_for_desc_disappear`	等待内容desc消失	`contentDesc`, `matchMode` （可选）， `timeoutMs`/`intervalMs` （可选）
`wait_for_activity`	等待当前活动/组件	`activity`, `matchMode` （可选）， `timeoutMs`/`intervalMs` （可选）
`wait_for_activity_change`	等待活动更改	`previousActivity`/`targetActivity` （可选）， `timeoutMs`/`intervalMs`
`press_key_sequence`	按顺序按下多个按键事件	`keyCodes`, `intervalMs` （可选）， `deviceId` （可选）
`tap_relative`	使用百分比坐标点击	`xPercent`, `yPercent`, `deviceId` （可选）
`swipe_relative`	使用百分比坐标滑动	`startXPercent`, `startYPercent`, `endXPercent`, `endYPercent`, `durationMs`
`scroll_vertical`	通过百分比滑动垂直滚动	`direction`, `distancePercent` （可选）， `deviceId` （可选）
`scroll_horizontal`	通过百分比滑动水平滚动	`direction`, `distancePercent` （可选）， `deviceId` （可选）
`smart_scroll`	滚动+自动等待+可选截图	`direction`, `profile`, `startXPercent`, `autoCorrectDirection`
`tap_center`	点击屏幕中央	`deviceId` （可选）
`long_press`	长按坐标	`x`, `y`, `durationMs` （可选）， `deviceId` （可选）
`double_tap`	双击坐标	`x`, `y`, `intervalMs` （可选）， `deviceId` （可选）
`wait_for_ui_stable`	等待UI转储稳定	`stableIterations`, `intervalMs`, `timeoutMs` （可选）
`get_screen_hash`	从当前转储中获取UI哈希	`deviceId` （可选）
`scroll_until_text`	滚动直到出现文本	`text`, `matchMode` （可选）， `maxScrolls` （可选）
`scroll_until_id`	滚动直到出现资源id	`resourceId`, `matchMode` （可选）， `maxScrolls` （可选）
`scroll_until_desc`	滚动直到出现内容描述	`contentDesc`, `matchMode` （可选）， `maxScrolls` （可选）
`wait_for_package`	在前台等待包裹	`packageName`, `timeoutMs`/`intervalMs` （可选）
`run_flow_plan`	快速执行多步骤UI计划	`steps`, `stopOnFailure`, `stepRetries`, `retryDelayMs`, `onFailSteps`
`query_ui`	按选择器查询UI节点	`selector`, `maxResults`, `useCache`, `maxAgeMs`, `deviceId` （可选）
`wait_for_node_count`	等待选择器匹配计数	`selector`, `count`, `comparator` （可选）
`tap_by_selector_index`	按索引匹配点击选择器	`selector`, `index` （可选）， `deviceId` （可选）
`ui_dump_cached`	返回上次缓存的UI转储	`deviceId`, `maxChars`, `maxAgeMs`, `invalidateOnActivityChange`, `refresh`
`reverse_android_port`	反向TCP端口（设备→ 主机）	`devicePort`, `hostPort` （可选）， `deviceId` （可选）
`forward_android_port`	转发TCP端口（主机→ 设备）	`devicePort`, `hostPort`, `deviceId` （可选）
`get_android_logcat`	获取最近的logcat输出	`lines` （可选）、过滤器， `deviceId` （可选）
`list_android_activities`	列出包的活动	`packageName`, `deviceId` （可选）
`hot_reload_android_app`	反向端口+安装/启动热开发	`packageName`, `reversePorts`，安装/启动选项，播放保护处理， `deviceId` （可选）
`create_github_issue`	创建GitHub问题	`title`, `body` （可选）， `labels` （可选）， `assignees` （可选）， `dryRun` （可选）

工具模式（已选择）

完整模式通过MCP服务器导出并实时导入 src/types.ts.

take_android_screenshot

{
  "name": "take_android_screenshot",
  "description": "Capture a screenshot from an Android device or emulator",
  "inputSchema": {
    "type": "object",
    "properties": {
      "deviceId": {
        "type": "string",
        "description": "Optional device ID. If not provided, uses the first available device."
      },
      "format": {
        "type": "string",
        "description": "Image format (png)."
      }
    }
  }
}

list_android_devices

{
  "name": "list_android_devices",
  "description": "List all connected Android devices and emulators with detailed information",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

find_android_apk

{
  "name": "find_android_apk",
  "description": "Find the most recent APK in a project directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "projectRoot": {
        "type": "string",
        "description": "Optional project root to search for APKs"
      }
    }
  }
}

安装android.apk

{
  "name": "install_android_apk",
  "description": "Install an APK on a connected Android device or emulator",
  "inputSchema": {
    "type": "object",
    "properties": {
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      },
      "apkPath": {
        "type": "string",
        "description": "Path to APK to install (optional; auto-detects if omitted)"
      },
      "apkUrl": {
        "type": "string",
        "description": "Optional URL to download an APK before installing"
      },
      "projectRoot": {
        "type": "string",
        "description": "Optional project root to search for APKs when apkPath is omitted"
      },
      "reinstall": {
        "type": "boolean",
        "description": "Reinstall if already installed (-r)"
      },
      "grantPermissions": {
        "type": "boolean",
        "description": "Grant runtime permissions at install time (-g)"
      },
      "allowTestPackages": {
        "type": "boolean",
        "description": "Allow installing test-only APKs (-t)"
      },
      "allowDowngrade": {
        "type": "boolean",
        "description": "Allow version downgrade (-d)"
      },
      "timeoutMs": {
        "type": "number",
        "description": "Optional timeout in milliseconds for install"
      },
      "playProtectAction": {
        "type": "string",
        "description": "How to handle Google Play Protect prompts (send_once, always, never)"
      },
      "playProtectMaxWaitMs": {
        "type": "number",
        "description": "Max time to wait for Play Protect prompt handling (milliseconds)"
      }
    }
  }
}

卸载安卓应用程序

{
  "name": "uninstall_android_app",
  "description": "Uninstall an app by package name",
  "inputSchema": {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "Android application package name"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      },
      "keepData": {
        "type": "boolean",
        "description": "Whether to keep app data and cache directories (-k)"
      }
    }
  }
}

start_android_app

{
  "name": "start_android_app",
  "description": "Start an Android app by package name",
  "inputSchema": {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "Android application package name"
      },
      "activity": {
        "type": "string",
        "description": "Optional activity to launch"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

stop_android_app

{
  "name": "stop_android_app",
  "description": "Force-stop an app",
  "inputSchema": {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "Android application package name"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

clear_android_app_data

{
  "name": "clear_android_app_data",
  "description": "Clear app data",
  "inputSchema": {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "Android application package name"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

get_android_currentactivity

{
  "name": "get_android_current_activity",
  "description": "Get the currently focused app activity",
  "inputSchema": {
    "type": "object",
    "properties": {
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

get_android_window_size

{
  "name": "get_android_window_size",
  "description": "Get device window size (physical/override)",
  "inputSchema": {
    "type": "object",
    "properties": {
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

dump_android_ui_层次结构

{
  "name": "dump_android_ui_hierarchy",
  "description": "Dump UI hierarchy XML from the device",
  "inputSchema": {
    "type": "object",
    "properties": {
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      },
      "maxChars": {
        "type": "number",
        "description": "Optional maximum number of characters to return"
      }
    }
  }
}

tap_android_screen

{
  "name": "tap_android_screen",
  "description": "Send a tap event to the device screen",
  "inputSchema": {
    "type": "object",
    "properties": {
      "x": {
        "type": "number",
        "description": "Tap X coordinate in pixels"
      },
      "y": {
        "type": "number",
        "description": "Tap Y coordinate in pixels"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

滑动_安卓_屏幕

{
  "name": "swipe_android_screen",
  "description": "Send a swipe gesture to the device screen",
  "inputSchema": {
    "type": "object",
    "properties": {
      "startX": {
        "type": "number",
        "description": "Start X coordinate in pixels"
      },
      "startY": {
        "type": "number",
        "description": "Start Y coordinate in pixels"
      },
      "endX": {
        "type": "number",
        "description": "End X coordinate in pixels"
      },
      "endY": {
        "type": "number",
        "description": "End Y coordinate in pixels"
      },
      "durationMs": {
        "type": "number",
        "description": "Optional swipe duration in milliseconds"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

input_android_text

{
  "name": "input_android_text",
  "description": "Type text into the focused input field",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "description": "Text to input into the focused field"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

send_android_eyevent

{
  "name": "send_android_keyevent",
  "description": "Send an Android keyevent",
  "inputSchema": {
    "type": "object",
    "properties": {
      "keyCode": {
        "type": "string",
        "description": "Android keycode (e.g., 3 for HOME, 4 for BACK, KEYCODE_ENTER)"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

reverse_android_port

{
  "name": "reverse_android_port",
  "description": "Reverse TCP port from device to host (useful for hot reload)",
  "inputSchema": {
    "type": "object",
    "properties": {
      "devicePort": {
        "type": "number",
        "description": "Device port to reverse"
      },
      "hostPort": {
        "type": "number",
        "description": "Host port to map to (defaults to devicePort)"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

forward_android_port

{
  "name": "forward_android_port",
  "description": "Forward TCP port from host to device",
  "inputSchema": {
    "type": "object",
    "properties": {
      "devicePort": {
        "type": "number",
        "description": "Device port to forward to (tcp)"
      },
      "hostPort": {
        "type": "number",
        "description": "Host port to forward from (tcp)"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

get_android_logcat

{
  "name": "get_android_logcat",
  "description": "Fetch recent logcat output (optionally filtered)",
  "inputSchema": {
    "type": "object",
    "properties": {
      "lines": {
        "type": "number",
        "description": "Number of log lines to return"
      },
      "since": {
        "type": "string",
        "description": "Optional time filter (e.g., \"1m\", \"2024-01-01 00:00:00.000\")"
      },
      "tag": {
        "type": "string",
        "description": "Optional log tag filter"
      },
      "priority": {
        "type": "string",
        "description": "Optional minimum priority (V/D/I/W/E/F/S)"
      },
      "pid": {
        "type": "number",
        "description": "Optional PID to filter logs by"
      },
      "packageName": {
        "type": "string",
        "description": "Optional package name to filter by running PID"
      },
      "format": {
        "type": "string",
        "description": "Logcat output format (time, threadtime, brief, raw)"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

list_android_活动

{
  "name": "list_android_activities",
  "description": "List activities for a package name",
  "inputSchema": {
    "type": "object",
    "properties": {
      "packageName": {
        "type": "string",
        "description": "Android application package name"
      },
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      }
    }
  }
}

hot_reload_android_app

{
  "name": "hot_reload_android_app",
  "description": "Reverse ports, install (optional), and start an app for hot reload",
  "inputSchema": {
    "type": "object",
    "properties": {
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      },
      "packageName": {
        "type": "string",
        "description": "Android application package name"
      },
      "activity": {
        "type": "string",
        "description": "Optional activity to launch"
      },
      "apkPath": {
        "type": "string",
        "description": "Optional APK path to install before starting"
      },
      "projectRoot": {
        "type": "string",
        "description": "Optional project root used to auto-detect APKs"
      },
      "reversePorts": {
        "type": "array",
        "description": "Ports to reverse (defaults to 8081)"
      },
      "install": {
        "type": "boolean",
        "description": "Whether to install an APK before starting"
      },
      "start": {
        "type": "boolean",
        "description": "Whether to start the app after setup"
      },
      "stopBeforeStart": {
        "type": "boolean",
        "description": "Whether to force-stop the app before starting"
      },
      "reinstall": {
        "type": "boolean",
        "description": "Reinstall if already installed (-r)"
      },
      "grantPermissions": {
        "type": "boolean",
        "description": "Grant runtime permissions at install (-g)"
      },
      "allowTestPackages": {
        "type": "boolean",
        "description": "Allow installing test-only APKs (-t)"
      },
      "allowDowngrade": {
        "type": "boolean",
        "description": "Allow version downgrade (-d)"
      },
      "timeoutMs": {
        "type": "number",
        "description": "Optional timeout in milliseconds for install"
      }
    }
  }
}

pm2_start_hot_mode

{
  "name": "pm2_start_hot_mode",
  "description": "Start the Android hot mode build in the background via PM2",
  "inputSchema": {
    "type": "object",
    "properties": {
      "projectRoot": {
        "type": "string",
        "description": "Optional project root to resolve config paths"
      },
      "configPath": {
        "type": "string",
        "description": "Optional PM2 config path (defaults to android_hot_mode.config.json)"
      },
      "appName": {
        "type": "string",
        "description": "Optional PM2 app name to start (filters config)"
      }
    }
  }
}

快速流动

{
  "name": "fast_flow",
  "description": "Run a fast UI flow with optional screenshots and UI dump",
  "inputSchema": {
    "type": "object",
    "properties": {
      "deviceId": {
        "type": "string",
        "description": "Optional device ID"
      },
      "actions": {
        "type": "array",
        "description": "Ordered list of actions to run"
      },
      "captureBefore": {
        "type": "boolean",
        "description": "Capture a screenshot before running the actions"
      },
      "captureAfter": {
        "type": "boolean",
        "description": "Capture a screenshot after running the actions"
      },
      "postActionWaitMs": {
        "type": "number",
        "description": "Optional wait after actions before capture/dump (milliseconds)"
      },
      "includeUiDump": {
        "type": "boolean",
        "description": "Include a UI hierarchy dump after the actions"
      },
      "uiDumpMaxChars": {
        "type": "number",
        "description": "Optional maximum number of characters to return from the UI dump"
      }
    }
  }
}

使用示例

_示例：AI代理列出设备、捕获屏幕截图并实时提供详细的UI分析_

实时UI开发

在您的开发环境（Expo、React Native、Flutter等）运行的情况下，与您的AI代理进行交互：

初步分析：

“截取我当前应用程序UI的屏幕截图并分析布局”
“显示登录屏幕的当前状态并提出改进建议”
“捕获应用程序并检查可访问性问题”

迭代开发：

“我刚刚更改了按钮的颜色，再拍一张截图并进行比较”
“帮助我调整间距-每次更改后都要截图”
“截取屏幕截图，告诉我新导航是否看起来不错”

跨平台测试：

“从我的手机和平板电脑模拟器中捕获屏幕截图”
“显示设备模拟器5554与我的物理设备上的UI外观”

开发调试：

“列出所有连接的设备及其状态”
“从运行我的调试版本的特定模拟器中截取屏幕截图”
“捕获当前错误状态并帮助我修复UI问题”

应用程序安装和交互：

“在此存储库中查找最新的APK并安装它”
“启动com.example.app并打开主活动”
点击（5401620）的登录按钮，然后键入我的测试凭据
运行批处理：点击电子邮件，键入，点击密码，键入，单击登录（一次通话）
反向端口8081进行热重新加载，然后重新启动应用程序
“获取com.example.app的最后200行logcat”

故障排除

亚洲开发银行问题

未找到ADB：验证ADB是否已安装并位于PATH中
无设备：检查USB连接和调试授权
设备未经授权：断开/重新连接USB，检查设备授权提示
截图失败：确保设备已解锁并正确连接

连接问题

验证 adb devices 将您的设备显示为“设备”状态
重新启动ADB服务器： adb kill-server && adb start-server
检查设备上的USB调试权限

发展

路线图

看 docs/ROADMAP.md 针对v3.0的具体方案。

构建命令

npm run build     # Production build
npm test          # Run tests
npm run lint      # Code linting
npm run format    # Code formatting

项目结构

src/
├── server.ts         # MCP server implementation
├── types.ts          # Type definitions
├── gui.ts            # Global GUI launcher entry
├── postinstall.ts    # Codex auto-config hook
├── utils/
│   ├── adb.ts        # ADB command utilities
│   ├── screenshot.ts # Screenshot processing
│   └── error.ts      # Error handling
└── index.ts          # Entry point

apps/gui/             # Electron GUI app
bin/                  # CLI launchers

演出

ADB操作超时5秒
内存截图处理
安全标准通信
最小权限执行

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

The Android MCP

快速接入

详细介绍