android-use

android-use

让 AI Agent 通过 ADB 查看并控制 Android 手机，同时内置安全防护措施。

android-use 是一款 Model Context Protocol（MCP）服务。任何支持 MCP 的应用（Claude Desktop、Claude Code、Cursor、Hermes Agent 等）都可以使用它在真实 Android 设备上截屏、读取屏幕上的 UI、点击、滑动、输入文字、按键和启动应用。从 v0.3 起，它还可以作为远程连接器运行：生成一个私有的 https://…/mcp URL，你可以将其粘贴到 Claude.ai、ChatGPT、Cursor、LibreChat、Open WebUI 或 LM Studio 中。

npx -y @ghostfacemodz/android-use          # local (stdio) MCP server
npx -y @ghostfacemodz/android-use setup    # guided setup as a remote connector (URL + key)

2 分钟快速上手

使用电脑（Windows、macOS 或 Linux）：

1. 安装 Node.js 18+ 和 adb（winget install Google.PlatformTools · brew install android-platform-tools · sudo apt install adb）。
2. 在手机上开启开发者选项 → USB 调试（或无线调试），连接手机并接受提示。（手机设置）
3. 运行：

   npx -y @ghostfacemodz/android-use setup
   

   程序会检查 adb、查找手机（并在需要时指导你执行 adb pair / adb connect）、创建专属密钥、启动服务，并询问你是否要通过免费的 Cloudflare quick tunnel 开启一个公开的 https:// 链接（程序会为你下载 cloudflared）。随后会显示你的连接器 URL、密钥和可复制粘贴的配置。
4. 将 URL 粘贴到你的 AI 应用中（用作连接器）。下次只需运行 npx -y @ghostfacemodz/android-use start --tunnel。

仅使用手机（无电脑、无需 root）：安装 Termux 并运行一条命令。请参阅docs/PHONE-ONLY.md。

**只想为 Claude Desktop / Cursor 配置本地 MCP 服务？**跳过设置，直接使用将其添加到 MCP 客户端中的 stdio 配置。

原名为 android-adb-mcp。工具、环境变量和行为均未改变；仅软件包名称、二进制名称（android-use）和 MCP 服务名称有所变更。

⚠️ **连接你在意的手机前，请先阅读安全。**借助此工具，AI 可以执行你通过点击屏幕能够执行的任何操作。

与 Google、Android 或 Samsung 无关联，也未获得其认可或赞助。“Android”是 Google LLC 的商标。

---

目录

• 功能介绍
• 可以用它做什么
• 它对手机有多大控制权
• 要求
• 手机设置
• 2 分钟快速上手
• 用作连接器（通过 HTTPS 连接远程 MCP）
• 仅用手机进行设置：Termux（docs/PHONE-ONLY.md）
• 将其添加到 MCP 客户端：Claude Desktop · Claude Code · Cursor · Hermes Agent · 其他客户端
• 配置
• 工具
• 安全
• 在远程电脑上运行（Tailscale + ADB）
• 使用场景与深入控制（docs/USE-CASES.md）
• 开发

功能介绍

android-use 是一个用于封装 adb 命令行工具的小型 TypeScript 封装。它通过 stdio（默认）或 Streamable HTTP（--http、setup、start）与 MCP 客户端通信，并有两个运行时依赖（@modelcontextprotocol/sdk 和 zod）。

示例：“打开 YouTube 并搜索 lo-fi beats。”

1. current_app → com.sec.android.app.launcher
2. open_app { package: "com.google.android.youtube" }
3. ui_dump → #4 ImageView [clickable] desc="Search" center=980,140 …
4. tap_element { text: "Search" }
5. type_text { text: "lo-fi beats" }，然后执行 key_event { key: "enter" }
6. 使用 screenshot 检查结果

可以用它做什么

你可以像平常一样与 AI 助手交流。它会规划步骤，并使用 android-use 在手机上执行：查看屏幕（ui_dump、screenshot）、执行操作（open_app、tap_element、tap、swipe、type_text、key_event），并在继续之前检查结果。手机必须处于解锁状态。

完整指南包含逐步演示、更多提示词以及每种用例的限制，详见 docs/USE-CASES.md。

腾出双手办事

在双手忙碌时播放视频或直播、播放音乐、打开导航，或设置闹钟或计时器。

真实示例： 一位通过 Tailscale 和 Wireless debugging 连接手机的助手，在主人离开手机时，通过一条聊天消息打开了某个 YouTube 频道的最新视频，然后切换到另一个频道的直播。

• “在 Spotify 上播放我的 Discover Weekly 播放列表，并把音量调高一点。”
• “打开 Google Maps，开始导航到最近的 Tesco。”
• “设置一个 12 分钟的计时器。”

提示： 如果不知道应用的包名，可以请求 list_apps。type_text 仅支持 ASCII，因此无法输入带重音符号的搜索内容或表情符号。了解详情 →

重复点击

清除通知、检查更新，或执行相同的日常流程，例如领取每日奖励。搭配可按计划运行的 AI Agent（例如通过 cron job 无头运行 Claude Code），即可每天早晨自动执行。

• “下拉通知栏并点击 Clear。” → 从顶部边缘执行 swipe → tap_element "Clear" → key_event home
• “打开 [game]，领取每日奖励，然后返回主屏幕。” → open_app → screenshot → tap_element "Collect" → key_event home
• “打开 Galaxy Store 并更新所有内容。”

限制： Google Play 默认列在敏感应用名单中（因为它可以进行购买），因此请使用 Play 自带的自动更新功能。手机锁定时，定时运行会失败。请遵守各应用的服务条款： 许多游戏和应用禁止自动化操作，可能会因此暂停账号。了解详情 →

通过手机发布社交内容

使用移动端专属功能，例如 TikTok 的编辑器或 Instagram Stories，无需第三方计划工具，因为助手操作的是真实应用。

• “用我最新的照片创建一条 Instagram Story，并在分享前停下来让我检查。”
• “用这段说明上传我最新的视频到 TikTok，并停留在 Post 界面。”
• “读给我听我最新帖子的评论。”（ui_dump + swipe）

确保有人参与审核： 让助手停在最终界面并发送一张 screenshot，由你亲自撰写或批准说明文字。无法输入表情符号。请遵守平台关于自动化活动的规则；不要批量点赞、关注或制造虚假互动。了解详情 →

无障碍功能

如果你觉得触摸屏难以操作，可以用日常语言和 AI 交谈或输入文字来控制手机，并让 AI 使用 ui_dump（屏幕上的文字）和 screenshot（图像和任何未标注的内容）读出屏幕内容。

• “我现在的屏幕上有什么？”
• “开启深色模式，并把文字调大。”
• “返回”、“向下滚动”、“调低音量。”（key_event back、swipe、key_event volume_down）

**请合理看待：**它是对 Android 内置工具（如 TalkBack 和 Voice Access）的补充，而非替代。这些工具在手机上运行，支持离线使用，也能在锁屏时使用。android-use 需要电脑、网络连接、AI 服务和已解锁的手机，而且速度较慢。了解详情 →

远程帮助家人

通过 Tailscale 和 ADB 调试，从任何地方帮家人调整设置：重新开启铃声、调大文字，或找回丢失的应用图标。将 ADB_SERIAL 设置为家人的手机，这样就不会误操作其他设备。

• “妈妈的手机不响了。把它切回响铃模式，并将铃声音量调到约 70%。”
• “把爸爸的字体调大一级，并开启粗体。”

**务必征得对方同意。**对方接受“允许 USB 调试？”提示后，即授予访问权限；他们也可以随时关闭 USB／无线调试或断开 Tailscale，以撤销权限。请保持敏感应用防护处于开启状态。了解详情 →

它对你手机的控制能力

简而言之：在 ADB 允许的范围内，并受下方防护措施限制，AI 能做任何你解锁屏幕后可以通过点击完成的操作。此说明基于 src/ 中的代码；完整说明提供了更多细节。

可以做	不能做	默认关闭
查看屏幕（screenshot）	绕过锁屏或 PIN 码	原始 shell 工具（ALLOW_SHELL=1）
以文本形式读取界面（ui_dump）	获取手机 Root 权限或系统权限	银行、支付、消息和密码应用（ALLOW_SENSITIVE=1）
点击、长按、滑动	读取应用的私有数据（聊天记录、数据库、已保存的登录信息）	设备允许列表：在你设置 ADB_SERIAL 之前处于关闭状态（建议设置）
输入文本（仅可打印的 ASCII 字符）	USB 调试和无线调试关闭时执行任何操作
按键（主页、返回、最近任务、音量、电源、回车等）	输入表情符号或非 ASCII 文本
打开应用、列出应用、查看前台应用	听取或拨打电话

更详细地说，它不能做什么。 它可以唤醒屏幕，但无法在没有你的 PIN 码、图案或密码的情况下解锁手机。ADB 以权限受限的 Android shell 用户身份运行，因此无法获取手机的 Root 权限，也无法读取其他应用的私有存储；它只能查看屏幕上显示的内容，应用标记为安全的屏幕会显示为黑屏。如果 USB 调试和无线调试均已关闭，或者手机尚未授权你的计算机，则任何操作都无法执行。

代码中已有的安全防护措施：

• 设备允许列表：ADB_SERIAL（默认：未设置，因此允许任何已连接的设备）。使用逗号分隔序列号；其他所有设备都会被拒绝，并从 list_devices 中隐藏。默认使用第一项。
• 敏感应用防护：除非设置 ALLOW_SENSITIVE=1，否则始终启用。 当敏感应用位于前台时，将拒绝 screenshot、ui_dump、tap、tap_element、swipe、long_press、type_text 和大多数按键操作；open_app 也不会启动此类应用。默认屏蔽的应用包括：Google Wallet、Samsung Wallet/Pay、PayPal、Venmo、Cash App、Zelle、Coinbase、WhatsApp、Telegram、Signal、Google Messages、Samsung Messages、Messenger 和 Google Play；此外，包名包含 bank、wallet、pay、finance、crypto、authenticator、messag、signal、keepass、bitwarden 或 1password 的应用也会被屏蔽。可通过 SENSITIVE_PACKAGES 添加更多应用。主页、返回、最近任务和电源键始终可用。此防护会匹配包名，因此只是尽力而为的启发式规则：许多银行应用需要手动添加。
• 原始 shell 默认关闭：ALLOW_SHELL。 除非将其设为 1，否则根本不会注册 shell 工具。启用后，该工具不受敏感应用防护限制。
• 速率限制：RATE_LIMIT_PER_MIN（默认：每滚动分钟 120 次调用）。
• **操作日志：**每次工具调用都会连同时间戳和参数写入 stderr；输入的文本只记录长度。

立即撤销访问权限：在手机上关闭无线调试或 USB 调试（或拔掉连接线）。若要彻底重置，请使用“开发者选项” → 撤销 USB 调试授权，断开 Tailscale，或重启手机（这会结束 adb tcpip 会话）。

建议的安全配置：

1. 将 ADB_SERIAL 设为仅包含你的手机。
2. 保持 ALLOW_SENSITIVE 和 ALLOW_SHELL 未设置。
3. 如果银行应用的名称不包含相关关键词，请将其添加到 SENSITIVE_PACKAGES。
4. 保持屏幕锁定，并在 Agent 操作时留意屏幕。
5. 在执行任何公开或付费操作之前，让助手先停止。
6. 使用完毕后关闭无线调试。

要求

• Node.js 18 或更高版本（提供 npx）
• ADB（Android platform-tools）已加入 PATH，或设置 ADB_PATH
  • macOS：brew install --cask android-platform-tools
  • Windows：winget install Google.PlatformTools，或下载 platform-tools 并将文件夹添加到 PATH
  • Linux：sudo apt install adb（或使用 platform-tools 压缩包）
  • 使用 adb version 检查
• 启用了 USB 调试或无线调试的 Android 手机（见下文）

手机设置

1. 启用开发者选项： 设置 → 关于手机（Samsung：→ 软件信息）→ 点按版本号 7 次。
2. 启用调试： 设置 → 开发者选项 → 开启USB 调试和／或无线调试（Android 11+）。
3. Samsung： 如果点按无响应，使用 ADB 时请关闭自动拦截器（设置 → 安全和隐私）。Xiaomi 和某些其他 ROM： 还需启用USB 调试（安全设置）。

通过 USB 连接： 插入手机，接受“允许 USB 调试？”提示，然后运行 adb devices。

无线连接（Android 11+）： 开发者选项 → 无线调试 → 使用配对码配对设备。该页面会显示一个 IP、一个配对端口和一个 6 位数代码；无线调试主页面会显示另一个连接端口。

adb pair 192.168.1.23:41234 123456     # pairing port + code
adb connect 192.168.1.23:37099         # connect port

你也可以让助手调用 connect_wifi { host, port, pairing_code, pair_port }。

运行 adb devices 并记下设备的序列号。你需要将它用于 ADB_SERIAL。

用作连接器（通过 HTTPS 连接远程 MCP）

在 HTTP 模式下，android-use 使用 MCP Streamable HTTP 传输，因此任何支持“通过 URL 添加 MCP 服务”的应用都可以使用你的手机。

端点	用途
POST/GET/DELETE /mcp	Streamable HTTP（当前 MCP 规范，通过 Mcp-Session-Id 管理会话）
GET /sse + POST /messages	旧版 HTTP+SSE 传输，适用于较早版本的客户端
GET /health	存活状态检查（无需身份验证，不会泄露手机信息）

启动

npx -y @ghostfacemodz/android-use setup             # guided: phone + token + optional public URL
npx -y @ghostfacemodz/android-use start --tunnel    # later: reuse saved phone + token, open a public URL
npx -y @ghostfacemodz/android-use start --funnel    # same, but a stable Tailscale Funnel URL
MCP_AUTH_TOKEN=... npx -y @ghostfacemodz/android-use --http --port 3333   # plain HTTP server, bring your own tunnel

setup 会在 ~/.config/android-use/token（Windows 上为 %APPDATA%\android-use\token）中保存令牌，并设置仅所有者可访问的权限；同时会将手机的序列号记在其旁边的 config.json 中。只有在交互式终端中运行时，它才会在复制粘贴配置中打印令牌（使用 --hide-token 隐藏，使用 --show-token 强制显示）。随时可以使用 cat ~/.config/android-use/token 再次读取。

公开 URL 选项：

选项	URL	说明
--tunnel（Cloudflare 快速隧道）	https://<random>.trycloudflare.com/mcp	免费，无需账户。会自动下载 cloudflared。每次重启 URL 都会变化，因此需要重新粘贴到应用中。需要出站端口 7844（某些网络会屏蔽该端口）。
--funnel（Tailscale Funnel）	https://<machine>.<tailnet>.ts.net/mcp	**稳定。**需要安装 Tailscale，并为你的 tailnet 启用 Funnel（若未启用，该命令会打印管理链接）。
命名 Cloudflare 隧道／你自己的反向代理	你的域名	稳定。将其指向 http://127.0.0.1:3333。

通用远程 MCP 配置

{
  "mcpServers": {
    "android-use": {
      "url": "https://YOUR-HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

有些应用无法发送自定义标头。对于这些应用，可以改为将令牌放在 URL 中：https://YOUR-HOST/mcp?key=YOUR_TOKEN。权衡： URL 比标头更容易泄露（可能出现在浏览器历史记录、屏幕截图、代理或应用日志以及共享的聊天记录中），因此仅在无法使用标头时才使用 ?key= 形式，切勿分享该 URL；如果令牌可能已泄露，请轮换令牌（删除令牌文件并重新运行 setup）。android-use 本身绝不会记录查询字符串。也接受 X-API-Key: YOUR_TOKEN。

应用专属片段

Claude.ai 和 Claude Desktop（自定义连接器）： 设置 → 连接器 → 添加自定义连接器 → 远程 MCP 服务 URL：https://YOUR-HOST/mcp?key=YOUR_TOKEN（OAuth 字段留空）。在 claude.ai 添加的自定义连接器也会显示在 Claude Desktop 和移动端中。若要改为在 Claude Desktop 中使用请求头，请通过 mcp-remote 在 claude_desktop_config.json 中进行桥接：

{
  "mcpServers": {
    "android-use": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOUR-HOST/mcp", "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer YOUR_TOKEN" }
    }
  }
}

Claude Code：

claude mcp add --transport http android-use https://YOUR-HOST/mcp --header "Authorization: Bearer YOUR_TOKEN"

Cursor（~/.cursor/mcp.json 或 .cursor/mcp.json）：

{
  "mcpServers": {
    "android-use": {
      "url": "https://YOUR-HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

ChatGPT（开发者模式）： 在网页版中，进入设置 → 应用 → 高级设置 → 开启 开发者模式，然后点击 创建应用（新版界面：插件 → + → 添加自定义 MCP 服务）。服务 URL：https://YOUR-HOST/mcp?key=YOUR_TOKEN，身份验证：无身份验证（URL 中的密钥即用于身份验证）。Plus、Pro、Business、Enterprise 和 Edu 套餐均可使用开发者模式。

LibreChat（librechat.yaml）：

mcpServers:
  android-use:
    type: streamable-http
    url: https://YOUR-HOST/mcp
    headers:
      Authorization: "Bearer ${ANDROID_USE_TOKEN}"   # set ANDROID_USE_TOKEN in LibreChat's .env
    timeout: 120000

Open WebUI： 管理员设置（或设置）→ 外部工具 → + → 类型：MCP (Streamable HTTP)，URL：https://YOUR-HOST/mcp，身份验证：Bearer，密钥：YOUR_TOKEN。在支持原生工具调用的模型的聊天中启用该工具。

LM Studio（程序 → 安装 → 编辑 mcp.json）：

{
  "mcpServers": {
    "android-use": {
      "url": "https://YOUR-HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

如果 LM Studio 在同一台电脑上运行，也可以直接访问 http://127.0.0.1:3333/mcp，无需隧道。

Venice： Venice 自带的聊天应用目前还不支持自定义 MCP 服务（该功能仍在其功能请求列表中，尚未发布）。你仍可通过在上述应用之一中将 Venice API 密钥添加为 OpenAI 兼容的服务提供商（https://api.venice.ai/api/v1），并在那里添加连接器，以便将 Venice 模型与 android-use 搭配使用。兼容的客户端包括 LibreChat、Open WebUI 或 LM Studio。

仅支持 HTTP+SSE 的旧版客户端： 使用 https://YOUR-HOST/sse（通过 Authorization 请求头，或使用 /sse?key=YOUR_TOKEN）。注意：Cloudflare quick 隧道会缓冲 GET 事件流，因此旧版 /sse 无法通过 --tunnel 使用；请改用 /mcp（默认返回纯 JSON，可正常工作）、Tailscale Funnel 或命名隧道。

Docker

该镜像在容器内的 0.0.0.0:3333 上以 HTTP 模式运行。容器中的 adb 通过网络连接手机（无线调试或 adb tcpip）；在 Linux 上也可使用 --device /dev/bus/usb 直通 USB。

docker build -t android-use .
docker run -d --name android-use -p 127.0.0.1:3333:3333 \
  -e MCP_AUTH_TOKEN="$(cat ~/.config/android-use/token)" \
  -e ADB_SERIAL=192.168.1.23:37099 \
  -v android-use-adb:/root/.android \
  android-use
docker exec -it android-use adb pair 192.168.1.23:41234 123456   # first time only
docker exec -it android-use adb connect 192.168.1.23:37099

/root/.android 卷会保留容器的 adb 密钥，因此手机无需再次请求授权。在 3333 端口前配置隧道或反向代理，即可获得公网 URL。

保持运行

scripts/keepalive.sh（位于此仓库以及 npm 包 $(npm root -g)/@ghostfacemodz/android-use/scripts/ 中）会在后台运行 android-use start，并在进程退出时将其重启（macOS/Linux/Termux）：

scripts/keepalive.sh start --tunnel     # or --funnel
scripts/keepalive.sh status             # running? + current public URL
scripts/keepalive.sh restart
scripts/keepalive.sh stop

日志写入 ~/.config/android-use/android-use.log，当前 URL 始终保存在 ~/.config/android-use/connection.json 中（令牌不会写入该文件）。在 Windows 上，可在保持打开的终端中运行 npx -y @ghostfacemodz/android-use start --tunnel，或使用 Task Scheduler / NSSM 将其包装运行。

连接器安全

• 必须提供令牌。 除非设置 MCP_ALLOW_NO_AUTH=1（仅适合在 127.0.0.1 上测试），否则 HTTP 模式必须配置 MCP_AUTH_TOKEN 或令牌文件才能启动。通过 setup 生成的令牌是 256 位随机值。
• 令牌采用恒定时间比较；失败尝试会记录日志，但不会记录令牌，并且每个客户端每分钟最多允许 10 次；请求会按客户端限流（HTTP_RATE_LIMIT_PER_MIN），此外还有工具调用限流（RATE_LIMIT_PER_MIN）。
• 默认绑定到 127.0.0.1，因此只有通过隧道（或同一台机器上的应用）才能访问。
• 默认允许任意来源的 CORS 请求，以支持基于浏览器的客户端；这很安全，因为身份验证使用令牌，而不是 Cookie。你也可以通过 MCP_CORS_ORIGINS 限制来源。
• 会话在空闲 30 分钟后过期；同时最多允许 50 个会话。
• 任何拥有 URL 和令牌的人都能控制你的手机（但仍受以下防护限制：设备锁定、无 Shell、敏感应用被阻止）。切勿分享 URL 和令牌。删除令牌文件并再次运行 setup 即可轮换令牌。若要立即切断访问，请停止服务或关闭无线调试／USB 调试。

将其添加到 MCP 客户端

所有客户端都运行相同的命令：npx -y @ghostfacemodz/android-use。设置 ADB_SERIAL 指定手机序列号是可选的，但强烈建议设置。编辑配置后，请重启客户端。

Claude Desktop

编辑 claude_desktop_config.json（设置 → 开发者 → 编辑配置）：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "android-use": {
      "command": "npx",
      "args": ["-y", "@ghostfacemodz/android-use"],
      "env": {
        "ADB_SERIAL": "R5CT1234ABC"
      }
    }
  }
}

Claude Code

claude mcp add android-use -- npx -y @ghostfacemodz/android-use

配置设备允许列表：

claude mcp add android-use --env ADB_SERIAL=R5CT1234ABC -- npx -y @ghostfacemodz/android-use

添加 --scope user，即可在每个项目中使用。运行 claude mcp list 查看。

Cursor

在项目中创建 .cursor/mcp.json，或创建 ~/.cursor/mcp.json 以便在所有位置使用：

{
  "mcpServers": {
    "android-use": {
      "command": "npx",
      "args": ["-y", "@ghostfacemodz/android-use"],
      "env": {
        "ADB_SERIAL": "R5CT1234ABC"
      }
    }
  }
}

Hermes Agent

在 ~/.hermes/config.yaml 的 mcp_servers 下添加：

mcp_servers:
  android_use:
    command: "npx"
    args: ["-y", "@ghostfacemodz/android-use"]
    env:
      ADB_SERIAL: "R5CT1234ABC"
    timeout: 120          # per-tool-call timeout in seconds
    connect_timeout: 60

重启 Hermes（或重新加载 MCP）。这些工具会以 mcp_android_use_ 为前缀显示，例如 mcp_android_use_screenshot。其他选项（如 tools.include／tools.exclude）请参阅 Hermes MCP 文档。

其他客户端（通用 stdio）

任何能够启动 stdio 服务的 MCP 客户端都可以使用：

字段	值
传输方式	stdio
命令	npx
参数	-y、@ghostfacemodz/android-use
环境变量（可选）	ADB_SERIAL、ALLOW_SHELL、ALLOW_SENSITIVE、SENSITIVE_PACKAGES、RATE_LIMIT_PER_MIN、ADB_PATH

或者全局安装，并直接使用 android-use 二进制文件：

npm install -g @ghostfacemodz/android-use
android-use        # speaks MCP over stdin/stdout; logs go to stderr

Windows 注意事项： 如果客户端找不到 npx，请将 "command": "cmd" 与 "args": ["/c", "npx", "-y", "@ghostfacemodz/android-use"] 配合使用。如果 adb 不在客户端的 PATH 中，请设置 ADB_PATH，例如 C:\\platform-tools\\adb.exe。

配置

所有配置均通过环境变量完成。

变量	默认值	含义
ADB_SERIAL	(任意设备)	设备序列号的逗号分隔允许列表（来自 adb devices）。拒绝所有其他设备。推荐。
ALLOW_SHELL	关闭	1 会注册原始 shell 工具。
ALLOW_SENSITIVE	关闭	1 会关闭敏感应用防护。
SENSITIVE_PACKAGES		要视为敏感应用的额外软件包名称（逗号分隔）。
RATE_LIMIT_PER_MIN	120	每分钟的工具调用上限。
ADB_PATH	adb	adb 二进制文件的路径。

HTTP / 连接器模式（--http、setup、start）：

变量 / 标志	默认值	含义
MCP_TRANSPORT=http / --http	stdio	在 /mcp 上提供 Streamable HTTP 服务（以及 /health 和旧版 /sse）。
PORT / --port	3333	监听端口。
HOST / --host	127.0.0.1	监听地址。仅在 Docker 中或防火墙后使用 0.0.0.0。
MCP_AUTH_TOKEN		客户端必须发送的令牌。没有令牌时，HTTP 模式拒绝启动。
MCP_AUTH_TOKEN_FILE	<config dir>/token	保存令牌的文件（setup 会以模式 600 创建此文件）。配置目录：~/.config/android-use（Linux/macOS/Termux）、%APPDATA%\android-use（Windows）或 ANDROID_USE_HOME。
MCP_ALLOW_NO_AUTH	关闭	1 允许 HTTP 无令牌运行。仅供本地测试。
MCP_CORS_ORIGINS	*	允许通过 CORS 访问的浏览器来源（逗号分隔）。
MCP_TRUST_PROXY	关闭（使用隧道时开启）	使用 CF-Connecting-IP / X-Forwarded-For 实施针对每个客户端的速率限制。
HTTP_RATE_LIMIT_PER_MIN	600	每个客户端每分钟的 HTTP 请求上限（登录失败：10 次/分钟）。
MCP_ENABLE_SSE	开启	0 会禁用旧版 /sse + /messages 端点。
MCP_JSON_RESPONSE	开启	0 会以 SSE 而非纯 JSON 的形式流式传输 POST 响应。
CLOUDFLARED_PATH	自动	使用此 cloudflared，而不是 PATH 中的版本或自动下载的版本。

工具

工具	功能
list_devices	已连接的设备（按允许列表筛选）
connect_wifi	adb pair（可选，需提供代码）+ adb connect host:port
screenshot	返回作为 MCP 图像的 PNG 截图
get_screen_size	屏幕分辨率（wm size）
tap	点击 x,y 坐标
swipe	在 ms 时间内从 x1,y1 滑动到 x2,y2
long_press	在 x,y 坐标按住 ms 毫秒
type_text	在当前焦点字段中输入文本（可打印 ASCII 字符，并经过安全引用处理）
key_event	home、back、recents、enter、power、volume_up/down、delete、tab、…或数字键码
open_app	按软件包名称启动应用
list_apps	已安装的软件包（默认仅列出第三方应用，可选筛选）
current_app	前台软件包
ui_dump	将 uiautomator dump 输出为紧凑列表，其中包含可点击/有标签的元素及其中心坐标
tap_element	按文本/content-desc 或 resource-id 查找元素并点击
shell	原始 adb shell。仅在 ALLOW_SHELL=1 时注册

除 list_devices 和 connect_wifi 外，每个工具都接受可选的 serial。

安全

这会让 AI 模型远程控制你的手机。 它可以发送消息、购物、更改设置、删除数据或读取屏幕上的任何内容。模型会出错，也可能受到其看到的文本诱导（来自网页、电子邮件或通知的提示词注入）。

内置防护：

• 设备许可列表： 设置 ADB_SERIAL，只有列表中的设备可以被控制。针对其他序列号的请求都会被拒绝。
• 敏感应用防护： 当银行、支付、钱包、消息或密码管理器应用处于前台时，screenshot、ui_dump、tap、swipe、type_text 和大多数按键操作都会被拒绝；open_app 也会拒绝启动这些应用。检测使用内置的软件包列表和关键词匹配（bank、pay、wallet、messag，等等）。这只是尽力而为的启发式检测，并非安全边界。主页、返回、最近任务和电源键始终可用，因此助手可以退出敏感应用。使用 ALLOW_SENSITIVE=1 可覆盖此限制。
• 默认不提供原始 Shell： 仅当设置 ALLOW_SHELL=1 时，才会提供 shell 工具。所有其他工具都会验证输入，并通过 execFile 调用 adb，不会在你的计算机上通过 Shell 调用。
• 速率限制： 默认每分钟最多调用 120 次工具（RATE_LIMIT_PER_MIN）。
• 日志记录： 每次工具调用都会记录到 stderr（你的 MCP 客户端日志）。输入的文本只会记录其长度。
• 默认仅限本地： 在 stdio 模式下，服务不会打开任何网络端口。HTTP 模式需显式启用，默认绑定到 127.0.0.1，且必须提供令牌才能启动（参见连接器安全）。屏幕截图和 UI 转储只会发送给请求它们的 MCP 客户端。你的客户端可能会将它们发送到云端大模型，因此请假定屏幕截图可能会通过你的 AI 服务提供商离开你的设备。

建议：尽可能使用备用或测试设备，锁定敏感应用，在 Agent 操作时留意屏幕，并在完成后关闭无线调试。

在远程计算机上运行（Tailscale + ADB）

在云端计算机或 VPS 上运行的 AI Agent 可以通过在该设备上运行 android-use 来控制手机：

1. 在手机和远程计算机上安装 Tailscale，并将两者加入同一 tailnet。确认两端都能看到对方的 Tailscale 地址。
2. Android 只允许从同一本地 Wi-Fi 网络进行无线调试配对，因此需要通过任意一台 PC 完成一次性 USB 设置：

   adb devices          # accept the prompt on the phone
   adb tcpip 5555
   

   然后拔下手机。
3. 在远程计算机上，连接：

   adb connect <phone-tailscale-ip>:5555
   

   并通过将手机加入许可列表来启动服务：

   ADB_SERIAL=<phone-tailscale-ip>:5555 npx -y @ghostfacemodz/android-use
   

4. 保持手机唤醒，并连接 Wi-Fi 或移动数据，同时确保 Tailscale 已连接。重启手机会关闭 TCP 模式，因此重启后请重复步骤 2。

完成后，请关闭 USB／无线调试，并断开手机上的 Tailscale 连接。

可选：使用 Twilio 进行 AI 语音通话（计划中）

状态： 计划中的附加功能，尚未开发。

ADB 可以发起、接听和挂断电话，但在没有 root 权限的情况下，Android 不允许应用在 SIM 卡实时通话中发声或收听。计划中的附加功能将改用 Twilio：使用一个 Twilio 号码，供助手拨出和接听电话，并提供文本转语音、通过 Twilio Media Streams 实时语音转文本，以及每次通话的文字记录和摘要。

准备工作：创建 Twilio 账户，购买支持语音通话的号码（每月约 $1.15，另加按分钟计费），并将账户 SID、身份验证令牌和号码作为机密信息保存（TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN、TWILIO_NUMBER）。切勿将它们提交到版本库。电话将通过 Twilio 号码拨出，而非你的 SIM 卡。许多司法管辖区（包括英国、美国和欧盟）要求告知对方其正在与 AI 对话或被录音，因此该桥接服务会在每次通话开始时播报此信息。请勿将其用于垃圾电话、自动拨号电话或冒充他人，并在 Twilio Console 中设置支出限额。

开发

git clone https://github.com/GhostFaceModz/android-adb-mcp
cd android-adb-mcp
npm install
npm test             # builds, then runs stdio + HTTP/auth + setup tests against a mocked adb (no phone needed)
node dist/index.js   # run the server from source

使用 MCP Inspector 测试已发布的软件包：

npx @modelcontextprotocol/inspector npx -y @ghostfacemodz/android-use

路线图

• 通过 scrcpy 实时流式传输屏幕
• 滚动直到找到目标，以及等待元素的辅助工具
• Unicode 文本输入（通过 ADB 键盘 IME）
• 按工具配置确认提示（MCP elicitation）
• 不支持 iOS，也没有支持计划（没有与 ADB 等效的方案）

许可证

MIT。请参阅 LICENSE。