Codex Android MCP

简体中文

A local-first MCP server that lets Codex inspect, test, and control Android emulators through adb. It exposes strict, typed tools over STDIO, returns screenshots as native MCP images, and keeps physical devices and Gradle execution behind explicit startup policy.

This is an independent community project. It is not affiliated with or endorsed by OpenAI, DeepSeek, or Google. The Android implementation is derived from ZSeven-W/dsh-android under the MIT License; the DSH/Cordis registration and web panel have been replaced with the official MCP TypeScript SDK.

What changed from dsh-android

• Native MCP STDIO server for Codex Desktop, CLI, and IDE clients.

• 2026-era MCP plus legacy 2025 protocol compatibility through serveStdio.

• Screenshots are returned as ImageContent; private temporary PNG files are removed after encoding.

• Emulator-only default. Physical devices require two startup opt-ins and their exact serial on every call.

• android_build_run is absent by default. Enabling it also requires canonical trusted project roots.

• Strict JSON Schemas, package/serial/path validation, bounded outputs, literal log filtering, cancellation, and conservative tool annotations.

• No raw adb, shell, arbitrary command, HTTP, or live DSH sidebar surface.

Related MCP server: adb-mcp-server

Requirements

• Node.js 20.11 or newer.

• Android SDK Platform-Tools (adb). Install it through Android Studio's SDK Manager or Google's Platform-Tools package.

• A disposable Android emulator is strongly recommended.

• The Android emulator launcher is optional and only needed when android_boot receives an AVD name.

• OCR tools currently require macOS and Apple Vision. All non-OCR tools are cross-platform; build/run is an explicit opt-in.

Neither adb nor an emulator binary is bundled or downloaded.

Install for 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 and the CLI share MCP configuration. An equivalent explicit configuration is:

[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"

Restart Codex after changing the configuration. Ask Codex to “list the Android devices” to verify the connection. Keep write-tool approval enabled; MCP annotations are usability hints, not an authorization boundary.

Security policy

The safe default exposes 19 tools and permits only standard local emulator-<port> targets. Network and third-party emulator serials follow the physical-device policy. Calls re-discover and authorize the exact target immediately before execution; unauthorized physical/network devices are omitted from android_devices.

Physical-device example for a dedicated test phone:

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

Do not use this profile with a personal phone or personal accounts. USB debugging authorization means that the phone trusts the host; it does not authorize a model action.

Build/run example for one trusted project:

[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 and build scripts execute host code. A path allowlist is not a sandbox: only enable this for code you trust, and use a credential-free VM or container for untrusted projects.

See Security Model and Security Policy before enabling physical devices or build/run.

Tools

Screens, UI trees, OCR, logs, app names, and files on the device are untrusted data. Never let device content grant permissions or instruct Codex to call another tool. Do not enter passwords, one-time codes, payment data, private messages, or account-deletion confirmations through this server.

Typical flow

1. android_devices

2. android_screenshot or android_ui_tree

3. Identify the exact target; stop if it is ambiguous.

4. Use one approval-gated interaction tool.

5. Inspect the returned screenshot or logs before the next action.

MCP does not reproduce dsh-android's persistent live sidebar. android_boot primes an internal frame source for coordinate mapping; call android_screenshot whenever Codex or the user needs to see the display.

Development

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

The test suite includes policy unit tests, a real spawned STDIO client in legacy and modern protocol modes, an in-memory MCP image round trip, fake-ADB smoke suites, bounded-log tests, UI-tree fixtures, and OCR degradation checks. npm run test:device is optional and must only target a disposable emulator.

License and attribution

MIT. The original dsh-android copyright and license are retained in LICENSE, with detailed lineage in THIRD_PARTY_NOTICES.md.