Codex Android MCP

简体中文

一个本地优先的 MCP 服务器，让 Codex 通过 adb 检查、测试和控制 Android 模拟器。它通过 STDIO 暴露严格、类型化的工具，将截图以原生 MCP 图片形式返回，并让物理设备与 Gradle 执行保持在显式启用策略之后。

这是一个独立的社区项目。它与 OpenAI、DeepSeek 或 Google 没有任何隶属关系，也没有获得它们的认可。Android 部分实现衍生自 MIT 许可下的 ZSeven-W/dsh-android；DSH/Cordis 注册和 Web 面板已被官方 MCP TypeScript SDK 取代。

与 dsh-android 的不同之处

• 面向 Codex Desktop、CLI 和 IDE 客户端的原生 MCP STDIO 服务器。

• 通过 serveStdio 提供 2026 时代的 MCP 以及旧版 2025 协议的兼容性。

• 截图以 ImageContent 返回；私有临时 PNG 文件在编码后删除。

• 默认仅限模拟器。物理设备需要两次启动选择，且每次调用都必须提供其精确序列号。

• android_build_run 默认不出现。启用它还需要受信任的规范项目根目录。

• 严格的 JSON Schema、软件包/序列号/路径验证、有界输出、字面量日志过滤、取消机制以及保守的工具注解。

• 没有原始 adb、shell、任意命令、HTTP 或实时 DSH 侧边栏。

Related MCP server: adb-mcp-server

要求

• Node.js 20.11 或更高版本。

• Android SDK Platform-Tools（adb）。通过 Android Studio 的 SDK Manager 或 Google 的 Platform-Tools 软件包 安装。

• 强烈建议使用可弃置的 Android 模拟器。

• Android 模拟器启动程序为可选，且仅在 android_boot 收到 AVD 名称时才需要。

• OCR 工具目前需要 macOS 和 Apple Vision。所有非 OCR 工具均跨平台；构建/运行需显式启用。

adb 或模拟器二进制文件都不会被捆绑或下载。

为 Codex 安装

git clone https://github.com/zifanersuotang/codex-android-mcp.git
cd codex-android-mcp
npm ci
npm run build
codex mcp add android -- node C:/absolute/path/to/codex-android-mcp/lib/index.js

Codex Desktop 和 CLI 共用 MCP 配置。一份等效的显式配置为：

[mcp_servers.android]
command = "node"
args = ["C:/absolute/path/to/codex-android-mcp/lib/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 1200
default_tools_approval_mode = "writes"

[mcp_servers.android.env]
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

修改配置后重启 Codex。要求 Codex“列出 Android 设备”以验证连接。保持“写入工具批准”启用；MCP 注解只是可用性提示，不是授权边界。

安全策略

安全的默认设置有 19 个工具，仅允许标准的本地 emulator-<port> 目标。网络和第三方模拟器序列号按物理设备策略处理。每次调用都会在执行前重新发现并授权精确目标；未授权的物理/网络设备会从 android_devices 中省略。

专用测试手机的物理设备示例：

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_PHYSICAL = "true"
ANDROID_MCP_ALLOWED_SERIALS = "EXACT_ADB_SERIAL"

不要将此配置用于个人手机或个人账号。USB 调试授权表示手机信任主机，并不代表模型行为被授权。

受信任项目的构建/运行示例：

[mcp_servers.android.env]
ANDROID_MCP_ALLOW_BUILD_RUN = "true"
ANDROID_MCP_ALLOWED_PROJECT_ROOTS = "C:/work/MyTrustedApp"
ANDROID_MCP_ALLOWED_SERIALS = "emulator-5554"

Gradle settings 和构建脚本会在主机上执行代码。路径允许列表不是沙箱：仅为值得信任的代码启用此功能；不可信项目请放到无凭据的 VM 或容器中。

在开通物理设备或构建/运行前，请先阅读安全模型和安全策略。

工具

屏幕、UI 树、OCR、日志、应用名称和设备上的文件均属于不可信数据。绝不要让设备内容授予权限或指示 Codex 调用 unknowing 工具。也不要通过本服务器输入密码、一次性验证码、支付资料、私人消息或删除账号的确认。

典型流程

1. 运行 android_devices

2. 运行 android_screenshot 或 android_ui_tree

3. 确定具体目标；如有歧义就停止。

4. 使用一个须经网关通过的交互工具。

5. 在下一步操作前检查返回的截图或日志。

MCP 不提供 dsh-android 那种常驻实时侧边栏。android_boot 会为坐标映射预置一个内部帧源；当 Codex 或用户需要看到屏幕时，请调用 android_screenshot。

开发

npm ci
npm run typecheck
npm test
npm pack --dry-run

测试套件包括策略单元测试、使用真实启动的 STDIO 客户端（旧版和现代协议两种模式）、内存内 MCP 图片往返、fake-ADB 冒烟测试、有界日志测试、UI 树固件和 OCR 降级检查。npm run test:device 为可选并有且仅能目标一次性的模拟器。

许可证与署名

MIT。原始 dsh-android 的版权和许可证保留在 LICENSE 中，有关更详细的全血缘关系见 THIRD_PARTY_NOTICES.md。