mcp-android

mcp-android

一个 Model Context Protocol 服务，可通过 ADB 控制 Android 手机——相当于 Mac 控制服务的手机版。Claude 可以查看屏幕（截图 + UI 层级），并进行点击、输入文本、按键、启动应用、设置闹钟/计时器以及读取通知等操作。默认安全，采用该套件的访问模式 + 标志模型。

它运行在你的电脑上，并控制通过 USB 或无线调试连接的手机（非常适合 Z Fold 7）。它不会安装在手机上，也不需要 root 权限。

iOS？ 原生 iPhone 无法通过这种方式控制——Apple 的沙盒禁止跨应用/系统自动化。有关可行方案（通过 USB 从 Mac 使用 Appium/WebDriverAgent），请参阅单独的 mcp-ios 仓库。

快速开始

brew install android-platform-tools        # provides adb
# On the phone: Settings → Developer options → enable USB (or Wireless) debugging, then authorize this computer
adb devices                                 # confirm your device shows "device"

直接从 npm 运行，无需克隆或构建：

npx -y @dockndevai/mcp-android

或者用一行命令将其添加到 Claude Code（从只读模式开始）：

claude mcp add android -e ANDROID_MODE="read-only" -- npx -y @dockndevai/mcp-android

Claude Desktop、Cursor、Codex、Windsurf 和 VS Code 的配置请参阅 docs/CLIENTS.md。

从源代码设置

brew install android-platform-tools        # provides adb
adb devices                                 # confirm your device shows "device"
npm install && npm run build

工具

读取（read-only+）：list_devices、device_info、screenshot、ui_dump、current_app、list_apps、get_notifications

写入（read-write+）：tap、swipe、input_text、press_key、launch_app、open_url、set_alarm、set_timer

管理（admin）：install_apk、uninstall_app、clear_app_data（需要 ANDROID_ALLOW_INSTALL）、run_shell（需要 ANDROID_ALLOW_SHELL；否则不会注册）

控制 UI 的典型操作流程：screenshot → ui_dump（查找边界）→ tap/input_text。

安全模型

事项	标志	默认值
可执行的操作	ANDROID_MODE	read-only
允许操作的包	ANDROID_PACKAGE_ALLOWLIST	（全部）
受保护的包（永不卸载/清除）	ANDROID_PROTECTED_PACKAGES	settings、systemui、gms
允许安装/卸载/清除	ANDROID_ALLOW_INSTALL	false
允许原始 adb shell	ANDROID_ALLOW_SHELL	false
交互式确认（破坏性操作）	MCP 询问（由客户端驱动）	（客户端支持时开启）
预览但不操作设备	ANDROID_DRY_RUN	false
审计日志（stderr）	ANDROID_AUDIT_LOG	true

当连接的客户端支持 MCP 询问时，破坏性工具（uninstall_app、clear_app_data、install_apk、run_shell）会暂停并请求用户批准具体操作后才会运行——模型无法代替你批准。如果客户端不支持询问，则由上方的访问模式 + 标志门控机制进行控制。

与 Claude Desktop / Claude Code 一起运行

{
  "mcpServers": {
    "android": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-android/dist/index.js"],
      "env": { "ANDROID_MODE": "read-write" }
    }
  }
}

提示词示例

• “截取我手机的屏幕，并告诉我屏幕上有什么。”
• “设置一个标记为 Gym、时间为上午 6:30 的闹钟。”
• “打开时钟应用并启动一个 10 分钟的计时器。”
• “我有哪些待处理的通知？”

开发

npm run dev
npm test          # security policy
npm run typecheck

许可证

MIT