android

Android MCP 服务

Android 诊断与取证 MCP——当应用崩溃、内存泄漏、耗电或行为异常时，就用它检查设备。

提供 76 个工具，覆盖 logcat / dumpsys / 软件包内部信息 / 系统属性 / 进程。包含 5 个 MCP 提示词（crash-investigation、memory-leak-detection、permission-audit、app-startup-profile、ui-element-locator）和 device-health 汇总功能。纯 ADB，无 Appium / uiautomator2 依赖。采用 2 级安全机制（写入 + shell 门控）。

它的独到之处

• 深入诊断——搜索 logcat / 提取崩溃信息、dumpsys（内存 / 图形 / CPU）、getprop、进程、软件包内部信息、应用 intent、端口转发。跨平台竞品通常不提供这些功能。
• MCP 提示词（5 个）——crash-investigation、memory-leak-detection、ui-element-locator、app-startup-profile、permission-audit。模型可直接调用的工作流模板。
• 汇总工具——device-health（一次调用即可获取电池 + 内存 + CPU + 网络信息）、analyze-app（软件包信息 + 内存 + Activity）。
• 2 级安全机制——ANDROID_MCP_ALLOW_WRITE（控制安装 / 点击 / 推送）和 ANDROID_MCP_ALLOW_SHELL（控制任意 adb shell）是独立的标志，对应不同的信任级别。
• 纯 ADB——无需 Appium、uiautomator2 或 Python 桥接。仅将官方 Android Debug Bridge 封装在 child_process 上。
• 专为节省令牌而设计——56 项 schema 精简、ANDROID_TOOLS/ANDROID_DISABLE 的 9 个类别，以及 search-tools 元工具。
• Apps SDK 卡片——通过 _meta["openai/outputTemplate"]，device-health 会在 ChatGPT 客户端中以快照卡片呈现（电池、RAM、Wi-Fi + 4 区块网格）。Claude 客户端会收到相同的 JSON 内容。
• stdio + Streamable HTTP——默认使用 stdio。设置 MCP_TRANSPORT=http，即可用于 ChatGPT Apps SDK 或远程客户端（通过 MCP_HTTP_TOKEN 进行 Bearer 身份验证）。

试试这些提示词

将服务连接到 Claude Desktop 或 Claude Code，然后粘贴以下任意提示词：

1. 调查崩溃——“我的应用 com.us-all.api 在这台 Pixel 6 模拟器上不断崩溃。提取最近的崩溃日志、出错的堆栈帧，以及近期权限变更。”
2. 检测内存泄漏——“追踪 com.us-all.api 在过去 5 分钟内的内存增长。显示堆内存变化、GC 压力和占用最大的分配器。”
3. 分析耗电原因——“这台设备上哪些项目在耗电？列出前 5 个耗电项、各自的持续时间，以及当前电池健康状况。”
4. 审计权限——“审计已安装的第三方应用，检查危险权限（位置 / 相机 / 通讯录 / 麦克风）。标记出过去 30 天未使用但持有这些权限的应用。”
5. 分析应用启动——“分析 com.us-all.api 的冷启动——测量 Activity 启动时间，找出初始化最慢的 fragment，并建议在哪里添加跟踪。”

何时使用此工具，而不是 mobile-next/mobile-mcp

mobile-next/mobile-mcp（4.7K★）是面向跨平台、以操作为导向的 MCP。两者解决的问题不同：

	mobile-mcp	@us-all/android-mcp（本项目）
平台	iOS + Android（跨平台）	仅 Android（专业工具）
定位	以操作为导向（“通过自然语言驱动应用”）	以诊断为导向（“告诉我出错的原因”）
UI 界面	优先使用无障碍树，循环执行操作	UI 层级结构 + 截图 + 诊断转储
诊断深度	最少	logcat / dumpsys / getprop / 进程 / 崩溃
聚合工具	—	device-health、analyze-app
MCP 提示词	—	5 个（诊断主题）
安全限制	基本	两层（写入和 shell 分开限制）
分发方式	广泛（12+ 个 IDE 按钮）	npm + Docker

两者可以同时使用，功能互补。 mobile-mcp 通过 QA 工作流驱动设备；当出现问题时，此 MCP 会告诉你问题出在哪里。尤其是：

• mobile-mcp 通过 UI 探索发现 Bug → 此 MCP 捕获崩溃日志和堆转储。
• mobile-mcp 无法告诉你启动速度慢的原因 → 此 MCP 提供 dumpsys gfxinfo 和 Activity 启动耗时。
• mobile-mcp 无法复现权限拒绝 → 此 MCP 显示确切的 dumpsys package 权限状态和最近的授权记录。

安装

Claude Desktop

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["-y", "@us-all/android-mcp"],
      "env": {
        "ANDROID_MCP_ALLOW_WRITE": "true"
      }
    }
  }
}

Claude Code

claude mcp add android -s user \
  -e ANDROID_MCP_ALLOW_WRITE=true \
  -e ANDROID_MCP_ALLOW_SHELL=true \
  -- npx -y @us-all/android-mcp

Docker

docker run --rm \
  --device /dev/bus/usb \
  -e ANDROID_MCP_ALLOW_WRITE=true \
  ghcr.io/us-all/android-mcp-server:latest

从源代码构建

git clone https://github.com/us-all/android-mcp-server.git
cd android-mcp-server && pnpm install && pnpm build
node dist/index.js

前提条件

• 已安装 ADB，且位于 PATH 中（或设置 ADB_PATH）
• 已启用 USB 调试的 Android 设备或模拟器
• 多设备配置时：使用 ANDROID_SERIAL=<serial> 指定目标设备

配置

变量	必需	默认值	说明
ANDROID_HOME	❌	自动检测	Android SDK 路径
ADB_PATH	❌	adb（PATH）	ADB 二进制文件路径
ANDROID_SERIAL	❌	自动（单台设备）	目标设备序列号
ANDROID_MCP_ALLOW_WRITE	❌	false	启用写入操作（安装、点击、推送）
ANDROID_MCP_ALLOW_SHELL	❌	false	启用任意 adb shell 执行
ANDROID_TOOLS	❌	—	逗号分隔的类别允许列表，可大幅节省 Token。
ANDROID_DISABLE	❌	—	逗号分隔的类别拒绝列表。设置 ANDROID_TOOLS 时会忽略此项。
MCP_TRANSPORT	❌	stdio	设置为 http 以启用 Streamable HTTP 传输
MCP_HTTP_TOKEN	有条件必需	—	Bearer 令牌。设置 MCP_TRANSPORT=http 时必需
MCP_HTTP_PORT	❌	3000	HTTP 监听端口
MCP_HTTP_HOST	❌	127.0.0.1	HTTP 绑定主机（localhost 会自动启用 DNS 重绑定保护）
MCP_HTTP_SKIP_AUTH	❌	false	跳过 Bearer 身份验证，例如：在已处理身份验证的反向代理后面运行时

类别（9 个）：device、apps、ui、logcat、emulator、files、system、debug、shell（始终受 ANDROID_MCP_ALLOW_SHELL 限制），另有始终启用的 meta。

使用 MCP_TRANSPORT=http 时：POST /mcp（Bearer 身份验证的 JSON-RPC）+ GET /health（公开的存活状态检查）。

Token 效率

场景	工具	Schema Token 数	相较默认值
默认（所有类别）	76	9,200	—
常用（ANDROID_TOOLS=device,ui,apps,logcat）	37	5,000	−46%
精简（ANDROID_TOOLS=device,ui）	19	2,500	−73%

此外还提供 search-tools 元工具（始终启用），用于在运行时发现工具。

只读模式（默认）

默认情况下，只允许读取操作。除非设置 ANDROID_MCP_ALLOW_WRITE=true，否则写入操作（tap、install-app、push-file 等）会返回错误。为加强安全性，执行 Shell 命令还需要单独设置 ANDROID_MCP_ALLOW_SHELL=true；即使已启用写入，除非明确设置此项，否则原始 shell 命令仍会被阻止。

MCP 提示词（5）

可通过 MCP prompts/list 使用的工作流模板：

• crash-investigation — 为目标软件包提取崩溃日志、堆栈帧和近期权限变更。
• memory-leak-detection — 跟踪一段时间内的堆内存变化；按分配器聚类。
• ui-element-locator — 根据视觉和无障碍提示查找 UI 元素；返回点击坐标。
• app-startup-profile — 冷启动性能分析：Activity 启动、Fragment 初始化和首帧。
• permission-audit — 标记权限过于宽泛、且使用不足的第三方应用。

MCP 资源

基于 URI 的只读实体：

• android://devices — 已连接的设备
• android://device/{serial} — 设备详情（型号／品牌／版本／显示）
• android://app/{packageName}/activities — 软件包公开的 Activity（exported／launchable 标志）
• android://device/{serial}/processes — 正在运行的进程

工具（76）

共 9 个类别。使用 search-tools 在运行时发现工具；完整列表已折叠如下。

类别	工具数
系统（电池／网络／设置／显示／方向／端口转发／Wi-Fi／移动数据）	19
应用（安装／启动／权限／Intent／清除数据）	14
UI（点击／滑动／截图／层级结构／无障碍／按索引标注点击／屏幕录制）	14
模拟器（AVD 启动／停止、快照管理）	7
设备（列表／信息／属性／无线连接）	5
调试（bugreport／内存／图形／CPU／doctor）	5
Logcat（捕获／筛选／清除／提取崩溃信息）	4
文件（列出／拉取／推送／删除）	4
Shell（受限的 execute-shell）	1
聚合（device-health、analyze-app）	2
元工具（search-tools）	1

完整工具列表

设备（5）

list-devices、get-device-info、get-device-properties、connect-device、disconnect-device

应用（14）

list-packages、get-package-info、install-app、uninstall-app、launch-app、stop-app、clear-app-data、grant-permission、revoke-permission、open-url、send-broadcast、get-current-activity、is-app-installed、get-app-intents

UI 自动化（14）

take-screenshot、dump-ui-hierarchy、ui-snapshot-a11y、tap、long-press、swipe、input-text、press-key、drag-and-drop、start-screen-recording、pull-screen-recording、double-tap、take-annotated-screenshot、tap-element

Logcat（4）

get-logcat、clear-logcat、search-logcat、get-crash-logs

模拟器（7）

list-avds、start-emulator、stop-emulator、list-snapshots、load-snapshot、save-snapshot、delete-snapshot

文件（4）

list-files、pull-file、push-file、delete-file

系统（19）

get-battery-info、get-network-info、change-setting、get-setting、set-display-size、set-display-density、keep-screen-on、port-forward、reverse-forward、list-forwards、remove-forward、toggle-wifi、toggle-mobile-data、open-notification、lock-device、unlock-device、get-orientation、set-orientation、list-settings

调试（5）

bugreport、get-mem-info、get-gfx-info、get-cpu-info、doctor

Shell（1）

execute-shell — 受 ANDROID_MCP_ALLOW_SHELL 控制

聚合

device-health — 一次调用获取电池、内存、CPU 和网络信息（响应约 7KB，包含 4 个子系统及注意事项）。 analyze-app — 聚合软件包信息、内存和 Activity 信息。

元工具

search-tools — 按关键词查询其他工具；始终启用。

架构

Claude → MCP stdio → src/index.ts
                      ├── adb.ts (execFile wrapper)
                      ├── tools/utils.ts (wrapToolHandler, shellEscape, validation)
                      └── tools/{device,apps,ui,logcat,emulator,files,system,debug,shell,aggregations}.ts
                                  ↓
                          ADB CLI (USB / TCP-IP / Emulator)
                                  ↓
                          Android Device

基于 @us-all/mcp-toolkit 构建：

• extractFields — 高效利用令牌的响应投影（ADB 扁平数组端点除外）
• aggregate(fetchers, caveats) — 用于 device-health／analyze-app 的扇出辅助函数
• createWrapToolHandler — 透传 WriteBlockedError／ShellBlockedError，并提供结构化 ADB 错误（{code, stderr}）
• wrapImageToolHandler（仅限 Android）— 清理 base64 PNG
• search-tools 元工具

安全性

• 默认只读。 未设置 ANDROID_MCP_ALLOW_WRITE=true 时，禁止写入。
• Shell 权限单独控制。 即使已启用写入，未设置 ANDROID_MCP_ALLOW_SHELL=true 时，仍禁止使用 execute-shell——信任级别彼此独立。
• 安全防护 Shell 注入。 使用 shellEscape 进行基于单引号的转义；通过 zod 正则白名单验证设置键、软件包名称、权限、组件、广播操作和附加数据。
• 禁止路径遍历。 设备路径必须是绝对路径，且不能包含 .. 或 Shell 元字符。
• 错误信息脱敏。 从所有错误输出中隐藏 API 密钥、令牌和密码。

技术栈

Node.js 22+ • TypeScript strict ESM • pnpm 10 • @modelcontextprotocol/sdk 1.29+ • zod v4 • fast-xml-parser • vitest（fork 池隔离）。

许可证

MIT